@open-mercato/shared 0.7.1-develop.7181.1.702cedc42c → 0.7.1-develop.7183.1.db9678eeb8

package/src/lib/i18n/__tests__/locale-registry.test.ts

@@ -0,0 +1,267 @@
+import { defaultLocale, locales } from '../config'
+import {
+  clearRegisteredLocales,
+  getRegisteredLocales,
+  getSupportedLocales,
+  isSupportedLocale,
+  registerLocales,
+  registerSupportedLocalesResolver,
+  resolveSupportedLocalesForRequest,
+} from '../locale-registry'
+import { resolveSupportedLocale, resolveLocaleFromAcceptLanguage } from '../locale'
+
+describe('locale registry', () => {
+  afterEach(() => {
+    clearRegisteredLocales()
+    registerSupportedLocalesResolver(null)
+  })
+
+  describe('with nothing registered (regression guard)', () => {
+    it('serves exactly the locales the platform ships, in order', () => {
+      expect(getSupportedLocales()).toEqual(['en', 'pl', 'es', 'de', 'ko'])
+      expect(defaultLocale).toBe('en')
+    })
+
+    it('returns the very same array instance as `locales`, so no copy can drift', () => {
+      expect(getSupportedLocales()).toBe(locales)
+    })
+
+    it('rejects a locale the platform does not ship', () => {
+      expect(isSupportedLocale('cs')).toBe(false)
+      expect(resolveSupportedLocale('cs')).toBeNull()
+    })
+  })
+
+  describe('registerLocales', () => {
+    it('adds a locale the platform does not ship', () => {
+      registerLocales(['cs'])
+
+      expect(isSupportedLocale('cs')).toBe(true)
+      expect(getSupportedLocales()).toEqual(['en', 'pl', 'es', 'de', 'ko', 'cs'])
+    })
+
+    it('keeps the shipped locales first so existing ordering is untouched', () => {
+      registerLocales(['cs', 'fr'])
+
+      expect(getSupportedLocales().slice(0, 5)).toEqual(['en', 'pl', 'es', 'de', 'ko'])
+    })
+
+    it('normalizes case, whitespace and underscores', () => {
+      registerLocales(['  CS  ', 'pt_BR'])
+
+      expect(getRegisteredLocales()).toEqual(['cs', 'pt-br'])
+    })
+
+    it('is idempotent', () => {
+      registerLocales(['cs'])
+      registerLocales(['cs'])
+
+      expect(getRegisteredLocales()).toEqual(['cs'])
+    })
+
+    it('ignores locales the platform already ships', () => {
+      registerLocales(['en', 'pl'])
+
+      expect(getRegisteredLocales()).toEqual([])
+      expect(getSupportedLocales()).toEqual(['en', 'pl', 'es', 'de', 'ko'])
+    })
+
+    it('ignores a code that is not a language, rather than throwing', () => {
+      expect(() => registerLocales(['not-a-language', 'zzz', ''])).not.toThrow()
+      expect(getRegisteredLocales()).toEqual([])
+    })
+
+    it('accepts a valid code even when a bad one is in the same batch', () => {
+      registerLocales(['zzz', 'cs'])
+
+      expect(getRegisteredLocales()).toEqual(['cs'])
+    })
+  })
+
+  describe('integration with locale resolution', () => {
+    it('makes a registered locale resolvable', () => {
+      expect(resolveSupportedLocale('cs')).toBeNull()
+
+      registerLocales(['cs'])
+
+      expect(resolveSupportedLocale('cs')).toBe('cs')
+    })
+
+    it('folds a region subtag down to a registered base locale', () => {
+      registerLocales(['cs'])
+
+      expect(resolveSupportedLocale('cs-CZ')).toBe('cs')
+    })
+
+    it('picks a registered locale out of an Accept-Language header', () => {
+      expect(resolveLocaleFromAcceptLanguage('cs-CZ,cs;q=0.9')).toBeNull()
+
+      registerLocales(['cs'])
+
+      expect(resolveLocaleFromAcceptLanguage('cs-CZ,cs;q=0.9')).toBe('cs')
+    })
+
+    it('still honours q-value ordering once extra locales exist', () => {
+      registerLocales(['cs'])
+
+      expect(resolveLocaleFromAcceptLanguage('cs;q=0.5,de;q=0.9')).toBe('de')
+    })
+  })
+
+  describe('clearRegisteredLocales', () => {
+    it('restores the shipped set', () => {
+      registerLocales(['cs'])
+      clearRegisteredLocales()
+
+      expect(getSupportedLocales()).toEqual(['en', 'pl', 'es', 'de', 'ko'])
+      expect(isSupportedLocale('cs')).toBe(false)
+    })
+  })
+
+  describe('resolveSupportedLocalesForRequest', () => {
+    it('serves the full set when no resolver is registered', async () => {
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl', 'es', 'de', 'ko'])
+    })
+
+    it('narrows the served set to the tenant selection', async () => {
+      registerSupportedLocalesResolver(async () => ['en', 'pl'])
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl'])
+    })
+
+    it('preserves the platform ordering rather than the tenant ordering', async () => {
+      registerSupportedLocalesResolver(async () => ['pl', 'en'])
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl'])
+    })
+
+    it('serves a tenant-selected locale that the app registered', async () => {
+      registerLocales(['cs'])
+      registerSupportedLocalesResolver(async () => ['en', 'cs'])
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'cs'])
+    })
+
+    it('drops a configured locale that has no dictionary source behind it', async () => {
+      registerSupportedLocalesResolver(async () => ['en', 'cs'])
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en'])
+    })
+
+    it('falls back to the full set when the selection matches nothing servable', async () => {
+      registerSupportedLocalesResolver(async () => ['cs', 'fr'])
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl', 'es', 'de', 'ko'])
+    })
+
+    it('treats "no stored selection" as no opinion', async () => {
+      registerSupportedLocalesResolver(async () => null)
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl', 'es', 'de', 'ko'])
+    })
+
+    it('treats an empty selection as no opinion', async () => {
+      registerSupportedLocalesResolver(async () => [])
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl', 'es', 'de', 'ko'])
+    })
+
+    it('normalizes the configured codes before matching', async () => {
+      registerSupportedLocalesResolver(async () => ['EN', ' pl '])
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl'])
+    })
+
+    it('never throws when the resolver fails — the root layout depends on it', async () => {
+      registerSupportedLocalesResolver(async () => {
+        throw new Error('database unavailable')
+      })
+
+      await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl', 'es', 'de', 'ko'])
+    })
+
+    describe('keeping the default locale servable', () => {
+      // `detectLocale` falls back to `defaultLocale` whenever neither the cookie
+      // nor Accept-Language matches. If the served set could exclude it, the page
+      // would render a language its own switcher does not list.
+      it('keeps the default locale in a selection that omits it', async () => {
+        registerSupportedLocalesResolver(async () => ['pl', 'de'])
+
+        await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl', 'de'])
+      })
+
+      it('keeps the platform ordering when it adds the default back', async () => {
+        registerSupportedLocalesResolver(async () => ['ko', 'de'])
+
+        await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'de', 'ko'])
+      })
+
+      it('does not duplicate the default locale when the selection includes it', async () => {
+        registerSupportedLocalesResolver(async () => ['en', 'pl'])
+
+        await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl'])
+      })
+
+      it('does not resurrect the default from a selection that matches nothing servable', async () => {
+        // An entirely unservable selection is a typo, not an opinion: the full
+        // set is the right answer, not a one-entry set containing only `en`.
+        registerSupportedLocalesResolver(async () => ['cs', 'fr'])
+
+        await expect(resolveSupportedLocalesForRequest()).resolves.toEqual(['en', 'pl', 'es', 'de', 'ko'])
+      })
+
+      it('always contains a locale `detectLocale` is allowed to return', async () => {
+        registerLocales(['cs'])
+        registerSupportedLocalesResolver(async () => ['pl', 'cs'])
+
+        const served = await resolveSupportedLocalesForRequest()
+
+        expect(served).toContain(defaultLocale)
+      })
+    })
+  })
+
+  describe('array identity', () => {
+    // `useSupportedLocales()` hands this array straight to callers, so a fresh
+    // identity on every call re-fires any `useEffect`/`useMemo` depending on it.
+    it('is stable across calls once a locale is registered', () => {
+      registerLocales(['cs'])
+
+      expect(getSupportedLocales()).toBe(getSupportedLocales())
+    })
+
+    it('changes identity when the set actually changes', () => {
+      const before = getSupportedLocales()
+      registerLocales(['cs'])
+
+      expect(getSupportedLocales()).not.toBe(before)
+    })
+
+    it('returns to the `locales` instance after clearing', () => {
+      registerLocales(['cs'])
+      clearRegisteredLocales()
+
+      expect(getSupportedLocales()).toBe(locales)
+    })
+  })
+
+  describe('isSupportedLocale normalization', () => {
+    // `registerLocales` normalizes what it stores, so the membership test has to
+    // normalize what it is asked about or the two disagree.
+    it('accepts a shipped locale regardless of case and padding', () => {
+      expect(isSupportedLocale('EN')).toBe(true)
+      expect(isSupportedLocale('  pl  ')).toBe(true)
+    })
+
+    it('accepts the canonical BCP-47 form of a registered region locale', () => {
+      registerLocales(['pt_BR'])
+
+      expect(isSupportedLocale('pt-BR')).toBe(true)
+      expect(isSupportedLocale('pt-br')).toBe(true)
+    })
+
+    it('still rejects a locale nobody registered', () => {
+      expect(isSupportedLocale('CS')).toBe(false)
+    })
+  })
+})

package/src/lib/i18n/config.ts

@@ -1,4 +1,41 @@
-export type Locale = 'en' | 'pl' | 'es' | 'de' | 'ko'
+/**
+ * The set of languages the platform ships dictionaries for.
+ *
+ * `Locale` is derived from `LocaleRegistry` rather than written as a closed
+ * union so that a downstream application can serve a language the platform does
+ * not ship, without patching or forking `@open-mercato/shared`. Augment the
+ * interface from the app and the new code becomes a valid `Locale` everywhere:
+ *
+ * ```ts
+ * declare module '@open-mercato/shared/lib/i18n/config' {
+ *   interface LocaleRegistry { cs: true }
+ * }
+ * ```
+ *
+ * Unaugmented, `Locale` resolves to exactly `'en' | 'pl' | 'es' | 'de' | 'ko'`,
+ * so existing exhaustive `Record<Locale, T>` maps keep their drift-guard value —
+ * and an app that opts in keeps exhaustiveness over its own extended set. This
+ * is the same `keyof SomeRegistry` + declaration-merging idiom TypeScript uses
+ * on itself (`NumberFormatOptionsStyleRegistry` in `lib.es5.d.ts`, additively
+ * merged with `unit` in `lib.es2020.intl.d.ts`).
+ *
+ * The type layer is advisory only: declaration merging applies when a package is
+ * *installed*, not when it is *enabled*, so it can claim a locale the running app
+ * never registered. `getSupportedLocales()` in `./locale-registry` is the single
+ * runtime authority, and every entry point validates against it.
+ */
+export interface LocaleRegistry {
+  en: true
+  pl: true
+  es: true
+  de: true
+  ko: true
+}
 
+export type Locale = keyof LocaleRegistry & string
+
+// NOTE: `scripts/dev.mjs` reads the next two declarations by regex (it parses
+// this file as text to build the dev splash screen before the app compiles).
+// Keep them as literal `export const <name>: <Type> = <literal>` statements.
 export const locales: Locale[] = ['en', 'pl', 'es', 'de', 'ko']
 export const defaultLocale: Locale = 'en'

package/src/lib/i18n/config.typecheck.tsx

@@ -0,0 +1,60 @@
+// Compile-time-only guard for the shape of `Locale`. Never imported at runtime:
+// `yarn typecheck` (`tsc --noEmit`) is the only gate that can catch a regression
+// here, because this repo's Jest transform runs with `isolatedModules: true` and
+// therefore skips type diagnostics.
+//
+// It sits outside `__tests__` because `packages/shared/tsconfig.json` excludes
+// that directory from `tsc --noEmit`, and it is a `.tsx` rather than a `.ts`
+// because the mutation gate mutates changed `src/lib/**/*.ts` files and runs only
+// their related Jest tests. See the identical reasoning in `context.typecheck.tsx`.
+//
+// What it protects: `Locale` is derived from `LocaleRegistry` so downstream apps
+// can widen it by declaration merging. That indirection must not accidentally
+// degrade it to `string`, which would silently delete every exhaustiveness check
+// the platform and its apps rely on.
+import type { Locale, LocaleRegistry } from './config'
+
+// 1. Unaugmented, `Locale` is still the exact five-member union.
+type Expected = 'en' | 'pl' | 'es' | 'de' | 'ko'
+type MutuallyAssignable<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
+const localeUnionIsUnchanged: MutuallyAssignable<Locale, Expected> = true
+
+// 2. It has NOT collapsed to `string` — that would make the union check above
+//    pass vacuously in one direction and destroy exhaustiveness everywhere.
+const localeIsNotWidenedToString: MutuallyAssignable<Locale, string> = false
+
+// 3. Every shipped code is assignable.
+const shipped: Locale[] = ['en', 'pl', 'es', 'de', 'ko']
+
+// 4. A code nobody registered is still rejected.
+// @ts-expect-error 'cs' is not a member of Locale until an app augments LocaleRegistry
+const unregistered: Locale = 'cs'
+
+// 5. Exhaustive `Record<Locale, T>` still works as a drift guard: omitting a
+//    member must remain an error, which is what apps depend on today.
+const exhaustiveLabels: Record<Locale, string> = {
+  en: 'English',
+  pl: 'Polski',
+  es: 'Español',
+  de: 'Deutsch',
+  ko: '한국어',
+}
+
+// @ts-expect-error a Record<Locale, …> missing `ko` must stay an error
+const nonExhaustiveLabels: Record<Locale, string> = {
+  en: 'English',
+  pl: 'Polski',
+  es: 'Español',
+  de: 'Deutsch',
+}
+
+// 6. The registry keys and the union stay in lockstep.
+const registryKeysMatchLocale: MutuallyAssignable<keyof LocaleRegistry & string, Locale> = true
+
+void localeUnionIsUnchanged
+void localeIsNotWidenedToString
+void shipped
+void unregistered
+void exhaustiveLabels
+void nonExhaustiveLabels
+void registryKeysMatchLocale

package/src/lib/i18n/context.tsx

@@ -1,6 +1,7 @@
 "use client"
 import { createContext, useContext, useMemo, type PropsWithChildren } from 'react'
 import type { Locale } from './config'
+import { getSupportedLocales } from './locale-set'
 
 export type Dict = Record<string, string>
 
@@ -17,6 +18,12 @@ export type I18nContextValue = {
   t: TranslateFn
   /** True when the locale is pinned via `OM_FORCE_LOCALE`; UI should hide switchers. */
   localeLocked: boolean
+  /**
+   * Every locale this app serves. Resolved on the server (where the app
+   * registry and any tenant configuration are readable) and handed to the
+   * client, because a client bundle cannot see either.
+   */
+  supportedLocales: readonly Locale[]
 }
 
 const I18N_CONTEXT_KEY = '__openMercatoI18nContext'
@@ -48,10 +55,20 @@ function format(template: string, params?: TranslateParams) {
   })
 }
 
-export function I18nProvider({ children, locale, dict, localeLocked = false }: PropsWithChildren<{ locale: Locale; dict: Dict; localeLocked?: boolean }>) {
+export function I18nProvider({ children, locale, dict, localeLocked, supportedLocales }: PropsWithChildren<{ locale: Locale; dict: Dict; localeLocked?: boolean; supportedLocales?: readonly Locale[] }>) {
+  // A nested provider (the backend layout mounts one inside the root layout's)
+  // shadows the whole subtree, so a prop it does not pass would otherwise be
+  // silently downgraded to the registry default for every consumer below it.
+  // Inheriting from the enclosing provider first makes an omitted prop mean
+  // "unchanged" rather than "reset", which is what a nested mount intends.
+  const outer = useContext(I18nContext)
   const value = useMemo<I18nContextValue>(() => ({
     locale,
-    localeLocked,
+    localeLocked: localeLocked ?? outer?.localeLocked ?? false,
+    // Falls back to the process-local registry so a provider mounted without the
+    // prop and without an enclosing one (tests, standalone renders) behaves
+    // exactly as it did before.
+    supportedLocales: supportedLocales ?? outer?.supportedLocales ?? getSupportedLocales(),
     t: (key, fallbackOrParams, params) => {
       let fallback: string | undefined
       let resolvedParams: TranslateParams | undefined
@@ -66,7 +83,7 @@ export function I18nProvider({ children, locale, dict, localeLocked = false }: P
       const template = dict[key] ?? fallback ?? key
       return format(template, resolvedParams)
     },
-  }), [locale, dict, localeLocked])
+  }), [locale, dict, localeLocked, supportedLocales, outer])
   return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>
 }
 
@@ -103,6 +120,16 @@ export function useOptionalLocale(): Locale | undefined {
   return ctx?.locale
 }
 
+/**
+ * Every locale this app serves, for rendering a language picker. Falls back to
+ * the process-local registry outside a provider so callers can render
+ * unconditionally.
+ */
+export function useSupportedLocales(): readonly Locale[] {
+  const ctx = useContext(I18nContext)
+  return ctx?.supportedLocales ?? getSupportedLocales()
+}
+
 /**
  * True when the active locale is pinned via `OM_FORCE_LOCALE`. Returns `false`
  * when no provider is in scope so callers can render unconditionally.

package/src/lib/i18n/locale-label.ts

@@ -0,0 +1,80 @@
+import type { TranslateFn } from './context'
+
+type ShippedLocaleLabel = {
+  /** Dictionary key, so the label itself is localized when a translator is given. */
+  key: string
+  /** Endonym — the language's name in its own language. */
+  native: string
+}
+
+// The locales the platform ships. Kept as literal data rather than derived from
+// `Intl.DisplayNames` because `Intl` disagrees on casing for some of them
+// (`español`, `polski`), and these strings are already user-visible.
+const SHIPPED_LOCALE_LABELS: Record<string, ShippedLocaleLabel> = {
+  en: { key: 'common.languages.english', native: 'English' },
+  pl: { key: 'common.languages.polish', native: 'Polski' },
+  es: { key: 'common.languages.spanish', native: 'Español' },
+  de: { key: 'common.languages.german', native: 'Deutsch' },
+  ko: { key: 'common.languages.korean', native: '한국어' },
+}
+
+// `resolveLocaleLabel` is called once per option per render of every language
+// switcher, and constructing an `Intl.DisplayNames` is not free. The answer for
+// a given code never changes within a process.
+const intlDisplayNames = new Map<string, string | undefined>()
+
+function resolveIntlDisplayName(locale: string): string | undefined {
+  if (intlDisplayNames.has(locale)) return intlDisplayNames.get(locale)
+  const resolved = computeIntlDisplayName(locale)
+  intlDisplayNames.set(locale, resolved)
+  return resolved
+}
+
+function computeIntlDisplayName(locale: string): string | undefined {
+  try {
+    // Ask for the language's name in its own language, so a switcher reads the
+    // way a speaker of that language expects it to.
+    const displayName = new Intl.DisplayNames([locale], { type: 'language' }).of(locale)
+    // `Intl` echoes the input back when it has no data for the code.
+    if (!displayName || displayName.toLowerCase() === locale.toLowerCase()) return undefined
+    return displayName
+  } catch {
+    // Invalid or unsupported code — fall through to the uppercased code.
+    return undefined
+  }
+}
+
+/**
+ * A human-readable name for any locale code, including ones the platform does
+ * not ship dictionaries for.
+ *
+ * Resolution order:
+ *  1. the shipped table — via `t` when given, so the label is itself localized
+ *     (a German UI shows "Polnisch"); otherwise the endonym ("Polski")
+ *  2. `Intl.DisplayNames` — the endonym for an arbitrary code, no dependency
+ *  3. the uppercased code — never blank
+ *
+ * Deliberately does **not** consult `./iso639`. Every caller of this function is
+ * a client component — the admin `ProfileDropdown`, the storefront
+ * `LanguageSwitcher`, the public checkout pay page — and `iso639.ts` is a
+ * 186-entry table with a module-scope `Set` no bundler can tree-shake, so
+ * importing it here would ship 7 KB of language catalogue to a conversion-
+ * critical public route in order to render five labels that rung 1 already
+ * answered. `Intl.DisplayNames` names essentially any code an app would plausibly
+ * register, in every browser this app supports, so the catalogue was only ever a
+ * fallback for a fallback. A code `Intl` cannot name degrades to its uppercased
+ * form, which is never blank. Server and admin callers that genuinely need the
+ * catalogue keep importing `getIso639Label` from `./iso639` directly.
+ *
+ * Pass `t` where the surrounding UI renders localized language names, and omit
+ * it where it renders endonyms. Both conventions exist in the codebase and the
+ * caller decides which one it wants.
+ */
+export function resolveLocaleLabel(locale: string, t?: TranslateFn): string {
+  const shipped = SHIPPED_LOCALE_LABELS[locale]
+  if (shipped) {
+    return t ? t(shipped.key, shipped.native) : shipped.native
+  }
+
+  return resolveIntlDisplayName(locale) ?? locale.toUpperCase()
+}

package/src/lib/i18n/locale-registry.ts

@@ -0,0 +1,142 @@
+import { defaultLocale, locales, type Locale } from './config'
+import { invalidateDictionaryCache } from './dictionary-cache'
+import { isValidIso639 } from './iso639'
+import { createLogger } from '../logger'
+import {
+  addRegisteredLocale,
+  clearRegisteredLocaleSet,
+  getSupportedLocales,
+  normalizeLocaleCode,
+} from './locale-set'
+
+// Constructed lazily rather than at module scope: a module-level factory call is
+// a side effect no bundler can drop, which would pin this whole module — and the
+// logger facade behind it — into any bundle that merely imports one of its
+// tree-shakeable exports.
+let cachedLogger: ReturnType<typeof createLogger> | null = null
+function logger() {
+  if (!cachedLogger) cachedLogger = createLogger('shared').child({ component: 'i18n-locale-registry' })
+  return cachedLogger
+}
+
+// The read side lives in `./locale-set`, which has no dependencies beyond
+// `./config` so client bundles can import it without pulling in the logger, the
+// ISO 639 table or the dictionary cache. Re-exported here so `locale-registry`
+// remains the one import path callers need to know about.
+export {
+  getSupportedLocales,
+  isSupportedLocale,
+  getRegisteredLocales,
+  normalizeLocaleCode,
+} from './locale-set'
+
+/**
+ * Register additional locales this application serves on top of the ones the
+ * platform ships in `locales`.
+ *
+ * Runtime half of the extension point; the compile-time half is augmenting
+ * `LocaleRegistry` in `./config`. Both are needed for an app-defined locale to
+ * be usable, and this one is the authority — the type layer cannot be trusted to
+ * reflect what the running app actually registered.
+ *
+ * Codes are normalized (`pt_BR` → `pt-br`) and validated against ISO 639-1;
+ * unknown codes are ignored with a warning rather than thrown, so one bad entry
+ * in app config cannot take the app down at boot. Registering is idempotent, and
+ * re-registering the shipped locales is a no-op.
+ */
+export function registerLocales(codes: readonly string[]): void {
+  let added = false
+
+  for (const code of codes) {
+    const normalized = normalizeLocaleCode(code)
+    if (!normalized) continue
+    if ((locales as readonly string[]).includes(normalized)) continue
+    // Region subtags (`pt-br`) are normalized but validated on their base code,
+    // matching how `resolveSupportedLocale` folds a region down to its language.
+    if (!isValidIso639(normalized.split('-')[0] ?? normalized)) {
+      logger().warn('Ignoring unknown locale code', { code })
+      continue
+    }
+    if (addRegisteredLocale(normalized)) added = true
+  }
+
+  // The dictionary a locale resolves to is derived from the supported set, so a
+  // widened set invalidates everything built from the narrower one.
+  if (added) invalidateDictionaryCache()
+}
+
+/** Drop every app-registered locale. Intended for tests. */
+export function clearRegisteredLocales(): void {
+  if (clearRegisteredLocaleSet()) invalidateDictionaryCache()
+}
+
+/**
+ * Resolves the locale codes the current tenant has opted into, or `null` when
+ * there is no tenant context or no stored selection.
+ */
+export type SupportedLocalesResolver = () => Promise<readonly string[] | null>
+
+const RESOLVER_GLOBAL_KEY = '__openMercatoI18nSupportedLocalesResolver__'
+
+type ResolverGlobalScope = typeof globalThis & {
+  [RESOLVER_GLOBAL_KEY]?: SupportedLocalesResolver | null
+}
+
+/**
+ * Register the source of per-tenant locale configuration.
+ *
+ * `@open-mercato/shared` cannot read tenant configuration itself — that needs a
+ * DI container and a domain module — so the owning module registers a resolver
+ * here, the same way `registerTranslationOverlayPlugin` inverts the dependency
+ * for content translations. With nothing registered the served set is exactly
+ * the process-local registry, which is today's behaviour.
+ *
+ * There is one slot: a second registration replaces the first. That is what
+ * makes an enterprise overlay able to take over the tenant lookup, so it is not
+ * an error, but it is warned about — silently losing the `translations` module's
+ * resolver to an accidental second call is otherwise undiagnosable.
+ */
+export function registerSupportedLocalesResolver(resolver: SupportedLocalesResolver | null): void {
+  const scope = globalThis as ResolverGlobalScope
+  if (resolver && scope[RESOLVER_GLOBAL_KEY]) {
+    logger().warn('Replacing an already-registered supported-locales resolver')
+  }
+  scope[RESOLVER_GLOBAL_KEY] = resolver
+}
+
+/**
+ * The locales to offer for the current request: the tenant's selection narrowed
+ * to those the app can actually serve.
+ *
+ * Intersecting rather than replacing means a code that was configured but has no
+ * dictionary source behind it can never reach a language switcher, so a typo in
+ * the settings screen cannot strand a tenant in a broken UI. An empty
+ * intersection falls back to the full set for the same reason. Never throws —
+ * this runs in the root layout, where a failure would take down every page.
+ */
+export async function resolveSupportedLocalesForRequest(): Promise<readonly Locale[]> {
+  const available = getSupportedLocales()
+  const resolver = (globalThis as ResolverGlobalScope)[RESOLVER_GLOBAL_KEY]
+  if (!resolver) return available
+
+  try {
+    const configured = await resolver()
+    if (!configured || configured.length === 0) return available
+
+    const selected = new Set(configured.map(normalizeLocaleCode))
+    if (!available.some((locale) => selected.has(locale))) return available
+
+    // `detectLocale` falls back to `defaultLocale` whenever neither the cookie
+    // nor Accept-Language matches, so the default has to stay servable. Without
+    // this, a tenant selecting only `['pl','de']` renders an English page whose
+    // own switcher does not list English: a blank Select trigger, no checked row
+    // in the profile menu, and no way for the user to get back.
+    selected.add(defaultLocale)
+    // Filtering `available` rather than mapping the selection preserves the
+    // platform's locale ordering instead of the tenant's.
+    return available.filter((locale) => selected.has(locale))
+  } catch (err) {
+    logger().warn('Failed to resolve tenant supported locales; serving the full set', { err })
+    return available
+  }
+}