@byline/i18n 2.6.0

package/src/formatter.test.node.ts

@@ -0,0 +1,163 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import { createFormatter } from './formatter.js'
+import type { TranslationBundle } from './types.js'
+
+const bundle: TranslationBundle = {
+  en: {
+    'byline-admin': {
+      'common.actions.save': 'Save',
+      'common.actions.cancel': 'Cancel',
+      'list.unread': '{count, plural, one {# unread} other {# unread}}',
+      'doc.publishedOn': 'Published on {date, date, medium}',
+      'errors.malformed': 'Hello {name', // unclosed brace — ICU parse failure
+    },
+    'plugin-x': {
+      'btn.go': 'Go',
+    },
+  },
+  fr: {
+    'byline-admin': {
+      'common.actions.save': 'Enregistrer',
+      // intentionally missing 'common.actions.cancel' — exercises default-locale fallback
+    },
+  },
+}
+
+describe('createFormatter — basic lookups', () => {
+  it('returns the active-locale translation for a known key', () => {
+    const f = createFormatter({ bundle, activeLocale: 'en', defaultLocale: 'en' })
+    expect(f.t('byline-admin', 'common.actions.save')).toBe('Save')
+  })
+
+  it('honours the active locale over the default locale', () => {
+    const f = createFormatter({ bundle, activeLocale: 'fr', defaultLocale: 'en' })
+    expect(f.t('byline-admin', 'common.actions.save')).toBe('Enregistrer')
+  })
+
+  it('looks up across namespaces independently', () => {
+    const f = createFormatter({ bundle, activeLocale: 'en', defaultLocale: 'en' })
+    expect(f.t('plugin-x', 'btn.go')).toBe('Go')
+  })
+})
+
+describe('createFormatter — ICU formatting', () => {
+  it('formats plurals correctly', () => {
+    const f = createFormatter({ bundle, activeLocale: 'en', defaultLocale: 'en' })
+    expect(f.t('byline-admin', 'list.unread', { count: 1 })).toBe('1 unread')
+    expect(f.t('byline-admin', 'list.unread', { count: 5 })).toBe('5 unread')
+  })
+
+  it('formats dates against the active locale', () => {
+    const f = createFormatter({ bundle, activeLocale: 'en', defaultLocale: 'en' })
+    const fixedDate = new Date('2026-05-28T00:00:00Z')
+    const result = f.t('byline-admin', 'doc.publishedOn', { date: fixedDate })
+    // Don't pin the exact phrasing — Intl output varies by Node version /
+    // ICU data — but it should contain the year and start with "Published".
+    expect(result).toMatch(/^Published on .*2026/)
+  })
+})
+
+describe('createFormatter — fallback chain', () => {
+  it('falls back to the default locale when the active locale misses', () => {
+    const onMissing = vi.fn()
+    const f = createFormatter({
+      bundle,
+      activeLocale: 'fr',
+      defaultLocale: 'en',
+      onMissing,
+    })
+    expect(f.t('byline-admin', 'common.actions.cancel')).toBe('Cancel')
+    expect(onMissing).toHaveBeenCalledTimes(1)
+    expect(onMissing).toHaveBeenCalledWith({
+      activeLocale: 'fr',
+      namespace: 'byline-admin',
+      key: 'common.actions.cancel',
+      fellThroughToKey: false,
+    })
+  })
+
+  it('falls back to the raw key when both locales miss', () => {
+    const onMissing = vi.fn()
+    const f = createFormatter({
+      bundle,
+      activeLocale: 'fr',
+      defaultLocale: 'en',
+      onMissing,
+    })
+    expect(f.t('byline-admin', 'does.not.exist')).toBe('does.not.exist')
+    expect(onMissing).toHaveBeenCalledTimes(1)
+    expect(onMissing).toHaveBeenCalledWith({
+      activeLocale: 'fr',
+      namespace: 'byline-admin',
+      key: 'does.not.exist',
+      fellThroughToKey: true,
+    })
+  })
+
+  it('reports each missing key only once per formatter instance', () => {
+    const onMissing = vi.fn()
+    const f = createFormatter({
+      bundle,
+      activeLocale: 'fr',
+      defaultLocale: 'en',
+      onMissing,
+    })
+    // Three calls for the same missing key.
+    f.t('byline-admin', 'common.actions.cancel')
+    f.t('byline-admin', 'common.actions.cancel')
+    f.t('byline-admin', 'common.actions.cancel')
+    expect(onMissing).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not fire onMissing when active and default are the same and the key exists', () => {
+    const onMissing = vi.fn()
+    const f = createFormatter({
+      bundle,
+      activeLocale: 'en',
+      defaultLocale: 'en',
+      onMissing,
+    })
+    f.t('byline-admin', 'common.actions.save')
+    expect(onMissing).not.toHaveBeenCalled()
+  })
+})
+
+describe('createFormatter — malformed messages', () => {
+  it('returns the raw key when ICU parsing fails', () => {
+    const onMissing = vi.fn()
+    const f = createFormatter({
+      bundle,
+      activeLocale: 'en',
+      defaultLocale: 'en',
+      onMissing,
+    })
+    expect(f.t('byline-admin', 'errors.malformed', { name: 'Alice' })).toBe('errors.malformed')
+  })
+
+  it('caches the parse failure so we do not re-parse on repeated calls', () => {
+    // No direct way to observe the cache, but the same call repeated should
+    // be cheap and produce the same fallback string deterministically.
+    const f = createFormatter({ bundle, activeLocale: 'en', defaultLocale: 'en' })
+    const first = f.t('byline-admin', 'errors.malformed')
+    const second = f.t('byline-admin', 'errors.malformed')
+    expect(first).toBe('errors.malformed')
+    expect(second).toBe('errors.malformed')
+  })
+})
+
+describe('createFormatter — exposed metadata', () => {
+  it('exposes activeLocale and defaultLocale', () => {
+    const f = createFormatter({ bundle, activeLocale: 'fr', defaultLocale: 'en' })
+    expect(f.activeLocale).toBe('fr')
+    expect(f.defaultLocale).toBe('en')
+  })
+})

package/src/formatter.ts

@@ -0,0 +1,166 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * ICU MessageFormat layer over a `TranslationBundle`. The expensive
+ * step in `intl-messageformat` is parsing the message string into its
+ * AST; once parsed, formatting against `values` is cheap. We cache the
+ * formatter by `(locale, namespace, key)` so a re-render that calls
+ * `t('foo')` a hundred times pays the parse cost exactly once.
+ *
+ * `createFormatter` returns a pure object: no React, no DOM, safe to
+ * use from server-side loaders, server functions, and Workers. The
+ * React hook in `./react` is a thin context wrapper around this.
+ *
+ * Fallback chain on lookup:
+ *   1. `bundle[activeLocale][namespace][key]`
+ *   2. `bundle[defaultLocale][namespace][key]`
+ *   3. The raw key — loud-by-default so missing translations are
+ *      visible in the UI during development.
+ *
+ * A miss in step 1 (but hit in step 2) invokes `onMissing` once per
+ * `(locale, namespace, key)` triple — the formatter dedups internally
+ * so repeated renders don't spam the console.
+ */
+
+import { IntlMessageFormat } from 'intl-messageformat'
+
+import type {
+  LocaleCode,
+  MessageKey,
+  Namespace,
+  TranslationBundle,
+  TranslationValues,
+} from './types.js'
+
+export interface FormatterOptions {
+  bundle: TranslationBundle
+  /** The locale to look up first. */
+  activeLocale: LocaleCode
+  /** Last-resort lookup before falling back to the raw key. */
+  defaultLocale: LocaleCode
+  /**
+   * Invoked once per `(locale, namespace, key)` triple when step 1
+   * misses but step 2 hits. Used by the React provider to emit
+   * `console.warn` lines in development. Pass `undefined` to suppress.
+   */
+  onMissing?: (event: MissingTranslationEvent) => void
+}
+
+export interface MissingTranslationEvent {
+  activeLocale: LocaleCode
+  namespace: Namespace
+  key: MessageKey
+  /** Whether the default-locale lookup also missed. */
+  fellThroughToKey: boolean
+}
+
+export interface Formatter {
+  /**
+   * Format a message for `namespace.key` with `values`. Always returns
+   * a string. ICU error paths (malformed message, missing required
+   * argument) fall through to the raw key rather than throwing — the
+   * admin shell should never crash because of a translation bug.
+   */
+  t(namespace: Namespace, key: MessageKey, values?: TranslationValues): string
+  readonly activeLocale: LocaleCode
+  readonly defaultLocale: LocaleCode
+}
+
+export function createFormatter(options: FormatterOptions): Formatter {
+  const { bundle, activeLocale, defaultLocale, onMissing } = options
+
+  // Cache key shape: `${locale}\0${namespace}\0${key}`. Null bytes
+  // separate the components so locales / namespaces / keys that happen
+  // to contain `:` or `.` (common in translation tooling) can't collide.
+  const formatterCache = new Map<string, IntlMessageFormat | null>()
+  const missingReported = new Set<string>()
+
+  function lookupMessage(
+    locale: LocaleCode,
+    namespace: Namespace,
+    key: MessageKey
+  ): string | undefined {
+    return bundle[locale]?.[namespace]?.[key]
+  }
+
+  function getFormatter(
+    locale: LocaleCode,
+    namespace: Namespace,
+    key: MessageKey
+  ): IntlMessageFormat | null {
+    const cacheKey = `${locale}\0${namespace}\0${key}`
+    const cached = formatterCache.get(cacheKey)
+    if (cached !== undefined) return cached
+    const message = lookupMessage(locale, namespace, key)
+    if (message == null) {
+      formatterCache.set(cacheKey, null)
+      return null
+    }
+    try {
+      const formatter = new IntlMessageFormat(message, locale)
+      formatterCache.set(cacheKey, formatter)
+      return formatter
+    } catch {
+      // Malformed message — cache the null so we don't re-parse on
+      // every render. The caller falls through to the next tier.
+      formatterCache.set(cacheKey, null)
+      return null
+    }
+  }
+
+  function reportMissing(namespace: Namespace, key: MessageKey, fellThroughToKey: boolean): void {
+    if (onMissing == null) return
+    const reportKey = `${activeLocale}\0${namespace}\0${key}\0${fellThroughToKey ? '1' : '0'}`
+    if (missingReported.has(reportKey)) return
+    missingReported.add(reportKey)
+    onMissing({ activeLocale, namespace, key, fellThroughToKey })
+  }
+
+  return {
+    activeLocale,
+    defaultLocale,
+    t(namespace, key, values) {
+      // Tier 1 — active locale.
+      const activeFormatter = getFormatter(activeLocale, namespace, key)
+      if (activeFormatter != null) {
+        return formatSafe(activeFormatter, values, key)
+      }
+
+      // Tier 2 — default locale.
+      if (defaultLocale !== activeLocale) {
+        const defaultFormatter = getFormatter(defaultLocale, namespace, key)
+        if (defaultFormatter != null) {
+          reportMissing(namespace, key, false)
+          return formatSafe(defaultFormatter, values, key)
+        }
+      }
+
+      // Tier 3 — raw key. Loud-by-default.
+      reportMissing(namespace, key, true)
+      return key
+    },
+  }
+}
+
+function formatSafe(
+  formatter: IntlMessageFormat,
+  values: TranslationValues | undefined,
+  fallbackKey: MessageKey
+): string {
+  try {
+    const out = formatter.format(values as Record<string, unknown> | undefined)
+    // `format` can return an array when rich-element interpolation is
+    // used. Phase 1 narrows the public API to string values only, so
+    // the array path shouldn't fire — but if it does, fall back to the
+    // raw key rather than returning `[object Object]`.
+    return typeof out === 'string' ? out : fallbackKey
+  } catch {
+    return fallbackKey
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `@byline/i18n` — admin interface translation primitives.
+ *
+ * Root entry: pure, React-free, safe to import from server contexts
+ * (loaders, server fns, Workers). Carries the type definitions, the
+ * `mergeTranslations` registry helper, the ICU formatter, and the
+ * locale-resolution cascade.
+ *
+ * The React surface (`<I18nProvider>`, `useTranslation`,
+ * `<LanguageMenu>`) lives at `@byline/i18n/react` — single barrel,
+ * single React Context identity, to sidestep the Vite `optimizeDeps`
+ * trap that has bitten this codebase before (see `@byline/ui`'s
+ * `react.ts` comment).
+ *
+ * Admin bundles (`adminTranslations(...)`, the English bundle) live
+ * at `@byline/i18n/admin`.
+ *
+ * See `docs/I18N.md` for the architecture.
+ */
+
+export { createFormatter } from './formatter.js'
+export { mergeTranslations } from './merge.js'
+export { resolveInterfaceLocale } from './resolve.js'
+export type {
+  Formatter,
+  FormatterOptions,
+  MissingTranslationEvent,
+} from './formatter.js'
+export type { MergeOptions, TranslationCollision } from './merge.js'
+export type { ResolveInterfaceLocaleOptions } from './resolve.js'
+export type {
+  LocaleCode,
+  LocaleDefinition,
+  MessageKey,
+  Namespace,
+  NamespaceTranslations,
+  TranslationBundle,
+  TranslationValues,
+} from './types.js'

package/src/merge.test.node.ts

@@ -0,0 +1,85 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import { mergeTranslations } from './merge.js'
+import type { TranslationBundle } from './types.js'
+
+describe('mergeTranslations', () => {
+  it('merges disjoint bundles into a single locale tree', () => {
+    const a: TranslationBundle = { en: { ns1: { foo: 'A' } } }
+    const b: TranslationBundle = { en: { ns2: { bar: 'B' } } }
+    const out = mergeTranslations(a, b)
+    expect(out).toEqual({ en: { ns1: { foo: 'A' }, ns2: { bar: 'B' } } })
+  })
+
+  it('later bundles override earlier bundles at the (locale, namespace, key) grain', () => {
+    const a: TranslationBundle = { en: { ns: { greeting: 'Hello' } } }
+    const b: TranslationBundle = { en: { ns: { greeting: 'Hi there' } } }
+    const out = mergeTranslations(a, b)
+    expect(out.en?.ns?.greeting).toBe('Hi there')
+  })
+
+  it('does not flag identical-value writes as collisions', () => {
+    const onCollision = vi.fn()
+    mergeTranslations(
+      { onCollision },
+      { en: { ns: { foo: 'same' } } },
+      { en: { ns: { foo: 'same' } } }
+    )
+    expect(onCollision).not.toHaveBeenCalled()
+  })
+
+  it('invokes onCollision once per actual override', () => {
+    const onCollision = vi.fn()
+    mergeTranslations(
+      { onCollision },
+      { en: { ns: { foo: 'A', bar: 'X' } } },
+      { en: { ns: { foo: 'B', baz: 'Y' } } }
+    )
+    expect(onCollision).toHaveBeenCalledTimes(1)
+    expect(onCollision).toHaveBeenCalledWith({
+      locale: 'en',
+      namespace: 'ns',
+      key: 'foo',
+      previousValue: 'A',
+      nextValue: 'B',
+    })
+  })
+
+  it('is associative — (a, (b, c)) === ((a, b), c)', () => {
+    const a: TranslationBundle = { en: { ns: { k1: '1', k2: 'A' } } }
+    const b: TranslationBundle = { en: { ns: { k2: 'B', k3: '3' } } }
+    const c: TranslationBundle = { en: { ns: { k1: 'X' } } }
+    const leftAssoc = mergeTranslations(mergeTranslations(a, b), c)
+    const rightAssoc = mergeTranslations(a, mergeTranslations(b, c))
+    expect(leftAssoc).toEqual(rightAssoc)
+    expect(leftAssoc.en?.ns).toEqual({ k1: 'X', k2: 'B', k3: '3' })
+  })
+
+  it('accepts undefined inputs and returns identity', () => {
+    const a: TranslationBundle = { en: { ns: { foo: 'A' } } }
+    expect(mergeTranslations(undefined, a, undefined)).toEqual(a)
+    expect(mergeTranslations()).toEqual({})
+  })
+
+  it('produces frozen output at every level', () => {
+    const out = mergeTranslations({ en: { ns: { foo: 'A' } } })
+    expect(Object.isFrozen(out)).toBe(true)
+    expect(Object.isFrozen(out.en)).toBe(true)
+    expect(Object.isFrozen(out.en?.ns)).toBe(true)
+  })
+
+  it('distinguishes a MergeOptions argument from a bundle by the onCollision function', () => {
+    const onCollision = vi.fn()
+    // First arg is MergeOptions (has `onCollision` function); second is a bundle.
+    const out = mergeTranslations({ onCollision }, { en: { ns: { foo: 'A' } } })
+    expect(out.en?.ns?.foo).toBe('A')
+  })
+})

package/src/merge.ts

@@ -0,0 +1,135 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Merge any number of `TranslationBundle`s into a single immutable
+ * registry. Last writer wins at the `(locale, namespace, key)` grain;
+ * collisions are reported via the optional `onCollision` callback
+ * (called once per replaced key) so callers can wire dev-mode warnings.
+ *
+ * Associative and deterministic — `merge(a, merge(b, c))` produces the
+ * same result as `merge(merge(a, b), c)`. Empty / undefined inputs are
+ * accepted and produce identity behaviour, so callers don't need
+ * conditional branching when a locale bundle is absent.
+ */
+
+import type { LocaleCode, MessageKey, Namespace, TranslationBundle } from './types.js'
+
+export interface MergeOptions {
+  /**
+   * Invoked once per collision (where a later bundle overrides an
+   * earlier bundle's value). Pure side effect — used by callers to
+   * emit `console.warn` lines in development. Production hosts can
+   * pass `undefined` to suppress.
+   */
+  onCollision?: (collision: TranslationCollision) => void
+}
+
+export interface TranslationCollision {
+  locale: LocaleCode
+  namespace: Namespace
+  key: MessageKey
+  /** The value that was already present and is being overwritten. */
+  previousValue: string
+  /** The value that replaces it. */
+  nextValue: string
+}
+
+/**
+ * Plain `Record<...>` mirror of `TranslationBundle` used internally
+ * while building up the merged registry. The public type is `Readonly`
+ * everywhere; we only freeze at the end.
+ */
+type MutableBundle = {
+  [locale: LocaleCode]: {
+    [namespace: Namespace]: { [key: MessageKey]: string }
+  }
+}
+
+export function mergeTranslations(
+  ...bundles: Array<TranslationBundle | undefined>
+): TranslationBundle
+export function mergeTranslations(
+  options: MergeOptions,
+  ...bundles: Array<TranslationBundle | undefined>
+): TranslationBundle
+export function mergeTranslations(
+  first: MergeOptions | TranslationBundle | undefined,
+  ...rest: Array<TranslationBundle | undefined>
+): TranslationBundle {
+  let options: MergeOptions = {}
+  let bundles: Array<TranslationBundle | undefined>
+  if (isMergeOptions(first)) {
+    options = first
+    bundles = rest
+  } else {
+    bundles = [first, ...rest]
+  }
+
+  const out: MutableBundle = {}
+  for (const bundle of bundles) {
+    if (bundle == null) continue
+    for (const locale of Object.keys(bundle)) {
+      const localeBundle = bundle[locale]
+      if (localeBundle == null) continue
+      let targetLocale = out[locale]
+      if (targetLocale == null) {
+        targetLocale = {}
+        out[locale] = targetLocale
+      }
+      for (const namespace of Object.keys(localeBundle)) {
+        const namespaceBundle = localeBundle[namespace]
+        if (namespaceBundle == null) continue
+        let targetNs = targetLocale[namespace]
+        if (targetNs == null) {
+          targetNs = {}
+          targetLocale[namespace] = targetNs
+        }
+        for (const key of Object.keys(namespaceBundle)) {
+          const nextValue = namespaceBundle[key]
+          if (nextValue == null) continue
+          const previousValue = targetNs[key]
+          if (previousValue !== undefined && previousValue !== nextValue) {
+            options.onCollision?.({
+              locale,
+              namespace,
+              key,
+              previousValue,
+              nextValue,
+            })
+          }
+          targetNs[key] = nextValue
+        }
+      }
+    }
+  }
+
+  return freezeBundle(out)
+}
+
+function isMergeOptions(value: unknown): value is MergeOptions {
+  // Bundles are locale-keyed at the top level (`{ en: {...}, fr: {...} }`)
+  // and their values are objects. MergeOptions has the `onCollision` key —
+  // a function — and no nested object-shaped sibling keys. Discriminate by
+  // looking for that function specifically; any object that isn't a bundle-
+  // shaped record falls through to the bundles path.
+  if (value == null || typeof value !== 'object') return false
+  const obj = value as Record<string, unknown>
+  return typeof obj.onCollision === 'function'
+}
+
+function freezeBundle(bundle: MutableBundle): TranslationBundle {
+  for (const locale of Object.keys(bundle)) {
+    const localeBundle = bundle[locale]
+    for (const namespace of Object.keys(localeBundle)) {
+      Object.freeze(localeBundle[namespace])
+    }
+    Object.freeze(localeBundle)
+  }
+  return Object.freeze(bundle) as TranslationBundle
+}

package/src/react/i18n-context.ts

@@ -0,0 +1,45 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * React Context module — kept in its own file (rather than inlined in
+ * `i18n-provider.tsx`) so both the provider and the hook import the
+ * same Context identity by path, and any consumer that imports from
+ * `@byline/i18n/react` shares it too. Splitting it across files would
+ * be fine on its own; what is NOT fine is splitting it across subpath
+ * exports — Vite's `optimizeDeps` can inline a private copy per
+ * subpath, breaking provider / consumer identity. The single `/react`
+ * subpath collapses both into one module graph.
+ */
+
+import { createContext } from 'react'
+
+import type { Formatter } from '../formatter.js'
+import type { LocaleCode, LocaleDefinition, TranslationBundle } from '../types.js'
+
+export interface I18nContextValue {
+  formatter: Formatter
+  bundle: TranslationBundle
+  activeLocale: LocaleCode
+  defaultLocale: LocaleCode
+  /**
+   * Permitted locale set with native names. `<LanguageMenu>` renders
+   * one row per entry; the resolver in the root package just needs the
+   * codes (`localeDefinitions.map(d => d.code)`).
+   */
+  localeDefinitions: readonly LocaleDefinition[]
+  /**
+   * Imperative locale change. Provided by the host adapter — typically
+   * calls a server fn that updates the user's stored preference and
+   * the cookie, then re-renders the provider with the new locale.
+   * When undefined the language switcher renders disabled.
+   */
+  setLocale?: (next: LocaleCode) => void | Promise<void>
+}
+
+export const I18nContext = createContext<I18nContextValue | null>(null)