@byline/i18n 2.6.0

package/src/react/i18n-provider.tsx

@@ -0,0 +1,76 @@
+/**
+ * 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 { type ReactNode, useMemo } from 'react'
+
+import { createFormatter, type MissingTranslationEvent } from '../formatter.js'
+import { I18nContext, type I18nContextValue } from './i18n-context.js'
+import type { LocaleCode, LocaleDefinition, TranslationBundle } from '../types.js'
+
+export interface I18nProviderProps {
+  bundle: TranslationBundle
+  activeLocale: LocaleCode
+  defaultLocale: LocaleCode
+  /** Permitted locale set with native names — drives `<LanguageMenu>`. */
+  localeDefinitions: readonly LocaleDefinition[]
+  /**
+   * Optional handler the host wires to its language-switcher server fn.
+   * Receives the new locale; expected to persist it and trigger a re-
+   * render with the updated `activeLocale` prop.
+   */
+  setLocale?: (next: LocaleCode) => void | Promise<void>
+  /**
+   * Override the dev-time `console.warn` on missing translations.
+   * Defaults to a one-shot warn per `(locale, namespace, key)` triple
+   * when `process.env.NODE_ENV !== 'production'`.
+   */
+  onMissing?: (event: MissingTranslationEvent) => void
+  children: ReactNode
+}
+
+export function I18nProvider({
+  bundle,
+  activeLocale,
+  defaultLocale,
+  localeDefinitions,
+  setLocale,
+  onMissing,
+  children,
+}: I18nProviderProps) {
+  const value = useMemo<I18nContextValue>(() => {
+    const onMissingResolved =
+      onMissing ?? (process.env.NODE_ENV !== 'production' ? defaultMissingWarner : undefined)
+    return {
+      formatter: createFormatter({
+        bundle,
+        activeLocale,
+        defaultLocale,
+        onMissing: onMissingResolved,
+      }),
+      bundle,
+      activeLocale,
+      defaultLocale,
+      localeDefinitions,
+      setLocale,
+    }
+  }, [bundle, activeLocale, defaultLocale, localeDefinitions, setLocale, onMissing])
+
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>
+}
+
+function defaultMissingWarner(event: MissingTranslationEvent): void {
+  if (event.fellThroughToKey) {
+    console.warn(
+      `[@byline/i18n] missing translation: ${event.activeLocale}.${event.namespace}.${event.key} — also missing in default locale; rendered raw key.`
+    )
+  } else {
+    console.warn(
+      `[@byline/i18n] missing translation: ${event.activeLocale}.${event.namespace}.${event.key} — using default-locale fallback.`
+    )
+  }
+}

package/src/react/index.ts

@@ -0,0 +1,26 @@
+/**
+ * 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
+ */
+
+/**
+ * Single React-side barrel. Provider + hook + language switcher all
+ * share one React Context identity by virtue of living behind this
+ * single subpath export — splitting across more subpaths would risk
+ * Vite `optimizeDeps` pre-bundling each subpath into a private copy of
+ * the Context module, breaking provider/consumer identity (see the
+ * `@byline/ui/src/react.ts` comment for the same trap in another
+ * package).
+ */
+
+export { I18nContext } from './i18n-context.js'
+export { I18nProvider } from './i18n-provider.js'
+export { LanguageMenu } from './language-menu.js'
+export { useTranslation } from './use-translation.js'
+export type { I18nContextValue } from './i18n-context.js'
+export type { I18nProviderProps } from './i18n-provider.js'
+export type { LanguageMenuProps } from './language-menu.js'
+export type { UseTranslationReturn } from './use-translation.js'

package/src/react/language-menu.tsx

@@ -0,0 +1,115 @@
+/**
+ * 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
+ */
+
+/**
+ * Self-contained language switcher. Reads `localeDefinitions`,
+ * `activeLocale`, and `setLocale` from `<I18nProvider>`'s context —
+ * the host wires the actual server fn (and admin-user update) behind
+ * `setLocale`; this component is pure UI.
+ *
+ * Renders nothing when fewer than two locales are configured, since
+ * the affordance has nothing to switch between.
+ *
+ * Host adapters typically mount this in the admin chrome top bar. It
+ * can also be embedded inside Account preferences (`<LanguageMenu />`
+ * with no className override) or anywhere else the menu makes sense.
+ */
+
+import { useContext, useState } from 'react'
+
+import { CheckIcon, Dropdown as DropdownMenu, GlobeIcon } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { I18nContext } from './i18n-context.js'
+import type { LocaleCode } from '../types.js'
+
+export interface LanguageMenuProps {
+  className?: string
+  /** Tailwind / CSS class applied to the icon + label colour. */
+  color?: string
+  /** Render the menu disabled (loading, no `setLocale`, etc.). */
+  disabled?: boolean
+}
+
+export function LanguageMenu({ className, color, disabled }: LanguageMenuProps) {
+  const context = useContext(I18nContext)
+  const [busy, setBusy] = useState(false)
+
+  if (context == null) {
+    throw new Error(
+      '[@byline/i18n] <LanguageMenu> must be used inside <I18nProvider>. Mount the provider in your admin shell root.'
+    )
+  }
+
+  const { activeLocale, localeDefinitions, setLocale } = context
+
+  if (localeDefinitions.length < 2) return null
+
+  const active = localeDefinitions.find((d) => d.code === activeLocale)
+  const isDisabled = disabled || setLocale == null || busy
+
+  const handleSelect = async (next: LocaleCode) => {
+    if (next === activeLocale || setLocale == null || busy) return
+    setBusy(true)
+    try {
+      await setLocale(next)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div className={className}>
+      <DropdownMenu.Root modal={false}>
+        <DropdownMenu.Trigger
+          render={
+            <button
+              type="button"
+              aria-label={active?.nativeName ?? activeLocale}
+              disabled={isDisabled}
+              className="component--byline-language-menu rounded flex items-center justify-between gap-1 outline-none disabled:opacity-50"
+            />
+          }
+        >
+          <GlobeIcon svgClassName={color} />
+          <span className={cx(color, 'hidden sm:inline mr-[4px]')}>
+            {active?.nativeName ?? activeLocale}
+          </span>
+        </DropdownMenu.Trigger>
+
+        <DropdownMenu.Portal>
+          <DropdownMenu.Content
+            align="center"
+            sideOffset={10}
+            className={cx(
+              'z-40 rounded radix-side-bottom:animate-slide-down radix-side-top:animate-slide-up',
+              'w-32 px-1.5 py-1 shadow-md',
+              'bg-white dark:bg-canvas-800 border dark:border-canvas-700 shadow'
+            )}
+          >
+            {localeDefinitions.map((def) => {
+              const isActive = def.code === activeLocale
+              return (
+                <DropdownMenu.Item key={def.code} onClick={() => handleSelect(def.code)}>
+                  <div className="flex">
+                    <span className="inline-block w-[22px]">
+                      {isActive && <CheckIcon width="18px" height="18px" />}
+                    </span>
+                    <span className="text-left inline-block w-full flex-1 self-start text-black dark:text-gray-300">
+                      {def.nativeName}
+                    </span>
+                  </div>
+                </DropdownMenu.Item>
+              )
+            })}
+          </DropdownMenu.Content>
+        </DropdownMenu.Portal>
+      </DropdownMenu.Root>
+    </div>
+  )
+}

package/src/react/use-translation.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
+ */
+
+import { useContext, useMemo } from 'react'
+
+import { I18nContext } from './i18n-context.js'
+import type { LocaleCode, MessageKey, Namespace, TranslationValues } from '../types.js'
+
+export interface UseTranslationReturn {
+  /** Format `namespace.key` against the provider's active locale. */
+  t: (key: MessageKey, values?: TranslationValues) => string
+  /** The active locale — useful for `<html lang>` and direction logic. */
+  locale: LocaleCode
+}
+
+/**
+ * Bind to a single namespace for the lifetime of the component. The
+ * returned `t` resolves keys against the active locale with default-
+ * locale fallback baked in (see `createFormatter` for the cascade).
+ *
+ * Throws if called outside `<I18nProvider>` — the loud failure is
+ * deliberate. A silently-broken admin shell with raw keys on screen
+ * is harder to notice than a thrown error during development.
+ */
+export function useTranslation(namespace: Namespace): UseTranslationReturn {
+  const context = useContext(I18nContext)
+  if (context == null) {
+    throw new Error(
+      '[@byline/i18n] useTranslation must be used inside <I18nProvider>. Mount the provider in your admin shell root.'
+    )
+  }
+  const { formatter, activeLocale } = context
+  return useMemo(
+    () => ({
+      t: (key, values) => formatter.t(namespace, key, values),
+      locale: activeLocale,
+    }),
+    [formatter, namespace, activeLocale]
+  )
+}

package/src/resolve.test.node.ts

@@ -0,0 +1,128 @@
+/**
+ * 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 } from 'vitest'
+
+import { resolveInterfaceLocale } from './resolve.js'
+
+const locales = ['en', 'fr', 'es']
+const defaultLocale = 'en'
+
+describe('resolveInterfaceLocale — tier 1 (preferred)', () => {
+  it('wins over every other signal when set and valid', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      preferred: 'fr',
+      cookie: 'es',
+      acceptLanguage: 'es;q=0.9, en;q=0.8',
+    })
+    expect(out).toBe('fr')
+  })
+
+  it('falls through when preferred is not in the permitted set', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      preferred: 'de',
+      cookie: 'es',
+    })
+    expect(out).toBe('es')
+  })
+
+  it('falls through when preferred is null', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      preferred: null,
+      cookie: 'fr',
+    })
+    expect(out).toBe('fr')
+  })
+})
+
+describe('resolveInterfaceLocale — tier 2 (cookie)', () => {
+  it('wins over Accept-Language', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      cookie: 'es',
+      acceptLanguage: 'fr;q=0.9',
+    })
+    expect(out).toBe('es')
+  })
+
+  it('falls through when cookie points at a removed locale', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      cookie: 'de',
+      acceptLanguage: 'fr;q=0.9',
+    })
+    expect(out).toBe('fr')
+  })
+
+  it('falls through when cookie is null', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      cookie: null,
+      acceptLanguage: 'fr;q=0.9',
+    })
+    expect(out).toBe('fr')
+  })
+})
+
+describe('resolveInterfaceLocale — tier 3 (Accept-Language)', () => {
+  it('picks the best match from the header', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      acceptLanguage: 'fr-CA;q=0.9, fr;q=0.8, en;q=0.5',
+    })
+    expect(out).toBe('fr')
+  })
+
+  it('falls back to default when no header language is in the permitted set', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      acceptLanguage: 'de;q=0.9, ja;q=0.5',
+    })
+    expect(out).toBe(defaultLocale)
+  })
+
+  it('handles malformed headers gracefully', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      acceptLanguage: 'this-is-not-a-valid-header',
+    })
+    // intl-localematcher returns the default when no match; this is the
+    // pure-fallback path.
+    expect(out).toBe(defaultLocale)
+  })
+})
+
+describe('resolveInterfaceLocale — tier 4 (default)', () => {
+  it('returns defaultLocale when every other tier produces nothing', () => {
+    const out = resolveInterfaceLocale({ locales, defaultLocale })
+    expect(out).toBe('en')
+  })
+
+  it('returns defaultLocale when every signal is empty', () => {
+    const out = resolveInterfaceLocale({
+      locales,
+      defaultLocale,
+      preferred: null,
+      cookie: null,
+      acceptLanguage: null,
+    })
+    expect(out).toBe('en')
+  })
+})

package/src/resolve.ts

@@ -0,0 +1,84 @@
+/**
+ * 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
+ */
+
+/**
+ * Pure locale-resolution cascade. Called once per request — server-side
+ * by the host adapter during request-context resolution; client-side
+ * during admin shell mount.
+ *
+ * Cascade (first non-null wins):
+ *   1. `preferred` — the authenticated admin user's stored preference
+ *      (`admin_users.preferred_locale`). Always wins when set.
+ *   2. `cookie`    — the `byline_admin_lng` cookie from the last language switch.
+ *   3. `acceptLanguage` — standards-compliant negotiation against the
+ *      permitted locale set via `@formatjs/intl-localematcher`.
+ *   4. `defaultLocale` — last-resort fallback.
+ *
+ * Every step validates the candidate against the permitted `locales`
+ * set, so a stale cookie pointing at a removed locale falls through
+ * cleanly rather than producing a locale the bundle can't satisfy.
+ */
+
+import { match } from '@formatjs/intl-localematcher'
+import Negotiator from 'negotiator'
+
+import type { LocaleCode } from './types.js'
+
+export interface ResolveInterfaceLocaleOptions {
+  /** Permitted locale set — from `i18n.interface.locales`. */
+  locales: readonly LocaleCode[]
+  /** Last-resort fallback — from `i18n.interface.defaultLocale`. */
+  defaultLocale: LocaleCode
+  /** `admin_users.preferred_locale` for the authenticated request, if any. */
+  preferred?: LocaleCode | null
+  /** Value of the `byline_admin_lng` cookie. */
+  cookie?: string | null
+  /** Raw `Accept-Language` request header. */
+  acceptLanguage?: string | null
+}
+
+export function resolveInterfaceLocale(options: ResolveInterfaceLocaleOptions): LocaleCode {
+  const { locales, defaultLocale, preferred, cookie, acceptLanguage } = options
+
+  // Tier 1 — admin user preference.
+  if (preferred != null && locales.includes(preferred)) {
+    return preferred
+  }
+
+  // Tier 2 — cookie.
+  if (cookie != null && locales.includes(cookie)) {
+    return cookie
+  }
+
+  // Tier 3 — Accept-Language negotiation.
+  if (acceptLanguage != null && acceptLanguage.length > 0) {
+    const matched = negotiateAcceptLanguage(acceptLanguage, locales, defaultLocale)
+    if (matched != null) return matched
+  }
+
+  // Tier 4 — default.
+  return defaultLocale
+}
+
+function negotiateAcceptLanguage(
+  header: string,
+  locales: readonly LocaleCode[],
+  defaultLocale: LocaleCode
+): LocaleCode | null {
+  try {
+    const negotiator = new Negotiator({
+      headers: { 'accept-language': header },
+    })
+    const requested = negotiator.languages()
+    if (requested.length === 0) return null
+    const matched = match(requested, locales as LocaleCode[], defaultLocale)
+    return locales.includes(matched) ? matched : null
+  } catch {
+    return null
+  }
+}

package/src/types.ts

@@ -0,0 +1,72 @@
+/**
+ * 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
+ */
+
+/**
+ * Locale code — kept as a plain `string` so the package stays open to
+ * any BCP 47 tag (`en`, `pt-BR`, `zh-Hans-CN`). The host's
+ * `i18n.interface.locales` config is the canonical allow-list at
+ * runtime; the resolver / validator narrow against it.
+ */
+export type LocaleCode = string
+
+/**
+ * Lightweight locale definition used by `<LanguageMenu>` to render the
+ * dropdown. The `code` matches a string in `i18n.interface.locales`;
+ * the `nativeName` is what the user sees ("English", "Español",
+ * "Français", "Deutsch", "日本語").
+ */
+export interface LocaleDefinition {
+  code: LocaleCode
+  nativeName: string
+}
+
+/**
+ * Namespace string — convention is `byline-<package>` for Byline-shipped
+ * code and `<org>-<plugin>` for third-party plugins. The runtime treats
+ * namespaces as opaque keys.
+ */
+export type Namespace = string
+
+/**
+ * Message key inside a namespace — dot-segmented by convention
+ * (`chrome.sidebar.collapse`), but the runtime treats keys as opaque.
+ */
+export type MessageKey = string
+
+/**
+ * One namespace's translations for one locale — flat key → ICU
+ * MessageFormat-encoded string.
+ */
+export type NamespaceTranslations = Readonly<Record<MessageKey, string>>
+
+/**
+ * The complete translation registry: locale → namespace → key →
+ * ICU-encoded message. Built by `mergeTranslations(...)`, passed to
+ * `<I18nProvider>`, and validated at boot by `@byline/core`.
+ *
+ * Bundles are deliberately plain JSON-shaped data — no functions, no
+ * React, no per-key metadata — so they can be authored as `.json`
+ * files, published as standalone npm packages, and round-tripped
+ * through any translation tool. Authoring-time metadata
+ * (descriptions, plural hints, deprecation markers) is a deferred
+ * Phase 4 surface; see `docs/I18N.md`.
+ */
+export type TranslationBundle = Readonly<{
+  [locale: LocaleCode]: Readonly<{
+    [namespace: Namespace]: NamespaceTranslations
+  }>
+}>
+
+/**
+ * Values argument to `t(key, values)`. `intl-messageformat` accepts
+ * strings, numbers, booleans, Dates, and React elements — but we narrow
+ * the public API to JSON-safe primitives + Date so the `t` return type
+ * stays `string`. Rich-element interpolation (e.g. inline links) goes
+ * through a separate `<Trans>` component (not part of the PR 1 surface).
+ */
+export type TranslationValues = Readonly<Record<string, string | number | boolean | Date | null>>