@ossy/locale

Framework-agnostic helpers for translation merge and lookup. Used by @ossy/app build, @ossy/platform server, @ossy/design-system runtime, and feature packages in server actions/tasks.

Browser-safe exports

import {
  parseLocaleFromTranslationFilename,
  isValidLocaleCode,
  parseTranslationCatalog,
  mergeTranslationFiles,
  resolveMessage,
  createTranslator,
} from '@ossy/locale'

Server-side lookup (actions, tasks, email)

Load the merged catalog from the app build output, then resolve keys with createTranslator or resolveMessage:

import path from 'node:path'
import { createTranslator } from '@ossy/locale'
import { loadMessagesForLanguage, createTranslatorForBuild } from '@ossy/platform/locale'

// Option A — helper loads manifest default language + fallback catalog
const buildDir = path.resolve(process.cwd(), 'build')
const t = createTranslatorForBuild(buildDir, 'sv')

await emailClient.send({
  to: user.email,
  from: '[email protected]',
  subject: t('authentication.verifySignIn.subject'),
  html,
  text,
})

// Option B — manual load when you already know the catalogs
const messages = loadMessagesForLanguage(buildDir, 'en')
const tEn = createTranslator(messages)
const label = tEn('authentication/request-sign-in.label')

Email templates

Keep React email components presentational; resolve copy in the action or task that sends the mail:

// request-sign-in.action.js
const t = createTranslatorForBuild(buildDir, language)
const subject = t('authentication.verifySignIn.subject')
const { html, text } = EmailRenderer.render(VerifySignInEmail, {
  token,
  baseUrl,
  t, // pass t into template props when body strings are localized
})

Translation keys for emails follow the same convention as UI: authentication.verifySignIn.subject, authentication.verifySignIn.body, etc.

Language selection

• HTTP requests: @ossy/platform resolves language from the URL and loads build/public/{language}.translations.json.
• Background tasks / events: use config.defaultLanguage from the app manifest until per-user locale is available.
• Fallback: createTranslatorForBuild loads the default-language catalog as fallbackCatalog when the active locale differs.

Key naming

See LOCALE-SPEC.md §3.3 — pages use {feature}.{pageSlug}.*, actions use {actionId}.label / {actionId}.description.