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

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

@@ -0,0 +1,98 @@
+import { locales, type Locale } from './config'
+
+// The read side of the locale registry, kept in its own module with no imports
+// beyond `./config` so it is safe — and cheap — to pull into a client bundle.
+// `context.tsx` is a "use client" module and needs `getSupportedLocales()`; if it
+// reached for `./locale-registry` instead it would drag the logger facade, the
+// dictionary cache and the ISO 639 table into every route that mounts
+// `I18nProvider`, because `./locale-registry` has module-level side effects that
+// no bundler can tree-shake away.
+//
+// Registration pattern for publishable packages.
+// Use globalThis to survive tsx/esbuild module duplication where the same file
+// can be loaded as multiple module instances when mixing dynamic and static
+// imports. The registry and the dictionary cache it invalidates must stay
+// coherent across those instances. Mirrors `../modules/registry.ts` and
+// `./dictionary-cache.ts`.
+const GLOBAL_KEY = '__openMercatoI18nLocaleRegistry__'
+const CACHE_KEY = '__openMercatoI18nSupportedLocales__'
+
+type LocaleSetGlobalScope = typeof globalThis & {
+  [GLOBAL_KEY]?: Set<string>
+  [CACHE_KEY]?: readonly Locale[] | null
+}
+
+function globalScope(): LocaleSetGlobalScope {
+  return globalThis as LocaleSetGlobalScope
+}
+
+function getRegistered(): Set<string> {
+  const scope = globalScope()
+  if (!scope[GLOBAL_KEY]) {
+    scope[GLOBAL_KEY] = new Set<string>()
+  }
+  return scope[GLOBAL_KEY]
+}
+
+/** `pt_BR` → `pt-br`. Applied on both sides of every comparison. */
+export function normalizeLocaleCode(value: string): string {
+  return value.trim().toLowerCase().replace(/_/g, '-')
+}
+
+/**
+ * Every locale this application can serve: the platform baseline plus anything
+ * registered by the app. The single runtime authority on the locale set — prefer
+ * it over importing `locales` directly anywhere a user-supplied value is being
+ * validated or a locale list is being rendered.
+ *
+ * Memoized so the returned array keeps a stable identity between mutations.
+ * `useSupportedLocales()` hands this straight to callers, and a fresh array on
+ * every render would re-fire any `useEffect`/`useMemo` that depends on it.
+ */
+export function getSupportedLocales(): readonly Locale[] {
+  const scope = globalScope()
+  const cached = scope[CACHE_KEY]
+  if (cached) return cached
+
+  const registered = getRegistered()
+  // With nothing registered this is `locales` itself, not a copy, so the common
+  // case allocates nothing and callers can compare by identity.
+  const resolved = registered.size === 0 ? locales : ([...locales, ...registered] as Locale[])
+  scope[CACHE_KEY] = resolved
+  return resolved
+}
+
+/** True when `code` is a locale this application serves. */
+export function isSupportedLocale(code: string): boolean {
+  return (getSupportedLocales() as readonly string[]).includes(normalizeLocaleCode(code))
+}
+
+/** Locales registered by the app, excluding the platform baseline. Test seam. */
+export function getRegisteredLocales(): readonly string[] {
+  return [...getRegistered()]
+}
+
+/**
+ * Add one already-normalized, already-validated code. Returns whether the set
+ * actually changed, so the caller knows when to invalidate what it derived.
+ * Internal to `./locale-registry` — applications call `registerLocales`.
+ */
+export function addRegisteredLocale(normalized: string): boolean {
+  const registered = getRegistered()
+  if (registered.has(normalized)) return false
+  registered.add(normalized)
+  globalScope()[CACHE_KEY] = null
+  return true
+}
+
+/**
+ * Drop every app-registered locale. Returns whether the set actually changed.
+ * Internal to `./locale-registry` — tests call `clearRegisteredLocales`.
+ */
+export function clearRegisteredLocaleSet(): boolean {
+  const registered = getRegistered()
+  if (registered.size === 0) return false
+  registered.clear()
+  globalScope()[CACHE_KEY] = null
+  return true
+}

package/src/lib/i18n/locale.ts

@@ -1,21 +1,35 @@
-import { locales, type Locale } from './config'
+import type { Locale } from './config'
+import { getSupportedLocales } from './locale-set'
 
 function normalizeLocaleToken(value: string): string {
   return value.trim().toLowerCase().replace(/_/g, '-')
 }
 
-export function resolveSupportedLocale(value: string | null | undefined): Locale | null {
+/**
+ * Canonicalize a user-supplied locale token against the set of locales that may
+ * be served, folding a region subtag down to its base language (`de-AT` → `de`).
+ *
+ * `supported` defaults to the process-wide set. Pass the request's served set —
+ * from `resolveSupportedLocalesForRequest()` — anywhere the answer is written
+ * somewhere durable, such as the `locale` cookie: the process-wide set is wider
+ * than a tenant's selection, so validating against it would accept a locale that
+ * every later render then discards, and report success while nothing changes.
+ */
+export function resolveSupportedLocale(
+  value: string | null | undefined,
+  supported: readonly Locale[] = getSupportedLocales(),
+): Locale | null {
   if (typeof value !== 'string') return null
 
   const normalized = normalizeLocaleToken(value)
   if (!normalized) return null
 
-  if (locales.includes(normalized as Locale)) {
+  if (supported.includes(normalized as Locale)) {
     return normalized as Locale
   }
 
   const baseLocale = normalized.split('-')[0]
-  if (baseLocale && locales.includes(baseLocale as Locale)) {
+  if (baseLocale && supported.includes(baseLocale as Locale)) {
     return baseLocale as Locale
   }
 
@@ -24,9 +38,10 @@ export function resolveSupportedLocale(value: string | null | undefined): Locale
 
 export function resolveLocaleFromCandidates(
   candidates: Iterable<string | null | undefined>,
+  supported?: readonly Locale[],
 ): Locale | null {
   for (const candidate of candidates) {
-    const resolved = resolveSupportedLocale(candidate)
+    const resolved = resolveSupportedLocale(candidate, supported)
     if (resolved) return resolved
   }
   return null
@@ -46,6 +61,7 @@ export function resolveForcedLocale(
 
 export function resolveLocaleFromAcceptLanguage(
   acceptLanguage: string | null | undefined,
+  supported?: readonly Locale[],
 ): Locale | null {
   if (typeof acceptLanguage !== 'string' || acceptLanguage.trim().length === 0) {
     return null
@@ -70,5 +86,5 @@ export function resolveLocaleFromAcceptLanguage(
       return left.index - right.index
     })
 
-  return resolveLocaleFromCandidates(rankedCandidates.map((entry) => entry.locale))
+  return resolveLocaleFromCandidates(rankedCandidates.map((entry) => entry.locale), supported)
 }

package/src/lib/i18n/server.ts

@@ -5,11 +5,18 @@ import { createFallbackTranslator, createTranslator } from './translate'
 import { tryGetModules } from '../modules/registry'
 import { loadAppDictionary } from './app-dictionaries'
 import { getCachedDictionary, setCachedDictionary } from './dictionary-cache'
+import { getSupportedLocales, resolveSupportedLocalesForRequest } from './locale-registry'
 
 // Re-export for backwards compatibility
 export { registerModules, getModules } from '../modules/registry'
 export { registerAppDictionaryLoader } from './app-dictionaries'
 export { invalidateDictionaryCache } from './dictionary-cache'
+export {
+  registerLocales,
+  getSupportedLocales,
+  registerSupportedLocalesResolver,
+  resolveSupportedLocalesForRequest,
+} from './locale-registry'
 
 function flattenDictionary(source: unknown, prefix = ''): Dict {
   if (!source || typeof source !== 'object' || Array.isArray(source)) return {}
@@ -26,22 +33,35 @@ function flattenDictionary(source: unknown, prefix = ''): Dict {
   return result
 }
 
-export async function detectLocale(): Promise<Locale> {
+export type DetectLocaleOptions = {
+  /**
+   * Restrict detection to this set — typically the current tenant's selection,
+   * resolved by the caller via `resolveSupportedLocalesForRequest()`. Omitted,
+   * detection uses the process-wide supported set, which is the prior behaviour.
+   */
+  supportedLocales?: readonly Locale[]
+}
+
+export async function detectLocale(options?: DetectLocaleOptions): Promise<Locale> {
   // Ops-level override: pin the whole app to one locale (default: unset).
   const forced = resolveForcedLocale(process.env)
   if (forced) return forced
+  const supported = options?.supportedLocales ?? getSupportedLocales()
   // Dynamic import to avoid requiring Next.js in non-Next.js contexts (CLI, tests)
   try {
     const { cookies, headers } = await import('next/headers')
     try {
       const c = (await cookies()).get('locale')?.value
-      if (c && locales.includes(c as Locale)) return c as Locale
+      if (c && supported.includes(c as Locale)) return c as Locale
     } catch {
       // cookies() may not be available outside request context (e.g., in tests)
     }
     try {
       const accept = (await headers()).get('accept-language') || ''
-      const match = resolveLocaleFromAcceptLanguage(accept)
+      // Matched against the served set rather than the process-wide one, so a
+      // header like `de, en` on a tenant that serves only `en` picks `en`
+      // instead of matching `de` first and then discarding the whole header.
+      const match = resolveLocaleFromAcceptLanguage(accept, supported)
       if (match) return match
     } catch {
       // headers() may not be available outside request context (e.g., in tests)
@@ -49,7 +69,14 @@ export async function detectLocale(): Promise<Locale> {
   } catch {
     // next/headers not available (CLI context)
   }
-  return defaultLocale
+  // The caller may have narrowed the set past the default locale, and returning
+  // a locale outside the served set would render a page whose own language
+  // switcher does not offer the language it is written in.
+  // `resolveSupportedLocalesForRequest` keeps `defaultLocale` in the set for
+  // exactly this reason; the `supported[0]` arm covers a caller that narrowed by
+  // hand and did not.
+  if (supported.includes(defaultLocale)) return defaultLocale
+  return supported[0] ?? defaultLocale
 }
 
 export async function loadDictionary(locale: Locale): Promise<Dict> {
@@ -58,9 +85,18 @@ export async function loadDictionary(locale: Locale): Promise<Dict> {
   // modules or the app dictionary loader are (re)registered.
   const cached = getCachedDictionary(locale)
   if (cached) return cached
+  // A locale the platform does not ship has no dictionaries of its own yet, and
+  // roughly a quarter of `t()` call sites pass no inline fallback — without a
+  // base layer those render as raw keys. Layering the default locale underneath
+  // makes an app- or operator-added locale degrade to English instead, which is
+  // what every comparable platform does. Shipped locales skip this entirely and
+  // keep their previous merge semantics byte for byte.
+  const needsDefaultLocaleBase =
+    locale !== defaultLocale && !(locales as readonly string[]).includes(locale)
+  const merged: Dict = needsDefaultLocaleBase ? { ...(await loadDictionary(defaultLocale)) } : {}
   // Load from registry instead of @/ import (works in standalone packages)
   const baseRaw = await loadAppDictionary(locale)
-  const merged: Dict = { ...flattenDictionary(baseRaw) }
+  Object.assign(merged, flattenDictionary(baseRaw))
   // Route handlers translate their responses, so they resolve a dictionary even
   // when they are exercised in isolation without a bootstrapped registry. The
   // app dictionary alone is the right degraded answer there — `registerModules`
@@ -74,8 +110,16 @@ export async function loadDictionary(locale: Locale): Promise<Dict> {
   return merged
 }
 
-export async function resolveTranslations() {
-  const locale = await detectLocale()
+/**
+ * Detect the locale and load its dictionary in one step.
+ *
+ * `options` is forwarded to `detectLocale`, so a caller that has already
+ * resolved the request's served set (a layout mounting its own `I18nProvider`)
+ * detects against that set instead of the process-wide one. Omitted — which is
+ * every route handler — behaviour is unchanged and no tenant lookup is made.
+ */
+export async function resolveTranslations(options?: DetectLocaleOptions) {
+  const locale = await detectLocale(options)
   const dict = await loadDictionary(locale)
   const t = createTranslator(dict)
   const translate = createFallbackTranslator(dict)

package/src/lib/testing/renderWithProviders.tsx

@@ -8,19 +8,21 @@ type ProviderOptions = {
   locale?: string
   dict?: Record<string, unknown>
   queryClient?: QueryClient
+  /** Narrow the served locale set, as the server does for a tenant selection. */
+  supportedLocales?: readonly string[]
 }
 
 export function renderWithProviders(
   ui: React.ReactElement,
   options?: RenderOptions & ProviderOptions,
 ) {
-  const { locale = 'en', dict = {}, queryClient = new QueryClient(), ...rest } = options ?? {}
+  const { locale = 'en', dict = {}, queryClient = new QueryClient(), supportedLocales, ...rest } = options ?? {}
 
   function Wrapper({ children }: { children: React.ReactNode }) {
     return (
       <QueryClientProvider client={queryClient}>
         {/* @ts-expect-error shared provider accepts loose dict shape */}
-        <I18nProvider locale={locale} dict={dict}>
+        <I18nProvider locale={locale} dict={dict} supportedLocales={supportedLocales}>
           {children}
         </I18nProvider>
       </QueryClientProvider>