@ultimat3/i18n 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -22,7 +22,19 @@ Imported by every package that renders a string.
   `registerCatalog` / `configureLocales` are its internals — an app calling them is a second path.
 - Reading: `t('ns.key')` for one string, `useI18n<AppCatalog>()` where the keys must be typed.
   There is no `currentTranslator`; `useI18n` replaced it.
+- **`configureLocales` is process-global and MERGES, so `resetLocaleConfig()` is the only way back.**
+  `defineCatalogs()` calls it at an app's module scope; a module evaluates once per `bun test` process,
+  so one file that loads an app narrowed `supported` for every file after it and `Accept-Language: de-DE`
+  negotiated `en` in a file that never mentioned locales. No partial call can widen the set back. The
+  test harness restores it at each file boundary (`@ultimat3/testing`'s `registry-snapshot.ts`).
 - A miss renders `⟦key⟧`. Never add a fallback locale chain — it hides gaps.
+- **`FRAMEWORK_CATALOG` registers under `FRAMEWORK_CATALOG_LOCALE` (`en`) only**, and
+  `registerFrameworkCatalog()` takes no locale — passing one is a compile error. It ran per locale
+  until 2026-08, so an `es`-only app served `Page not found` and English `ui.*` chrome with
+  `isMiss` reading FALSE, which is the fallback chain the line above refuses, wearing registration
+  as a disguise. It is also a real no-op when the locale already has a catalog: `registerCatalog`
+  merges its ARGUMENT last, so a second call reverted every app override of a framework key.
+  A non-`en` app translates the framework keys it renders into its own catalog.
 - Only an **own** property of `vars` is a variable — `interpolate` guards with `Object.hasOwn`.
   A plain object inherits `constructor`, `toString`, `valueOf` and `__proto__`, so a bare
   `vars[name]` rendered a function's source into the page for a template nobody wrote a variable

package/README.md

@@ -35,7 +35,7 @@ export const useT = (): Translator<AppCatalog> => useI18n<AppCatalog>();
 | One call | Because |
 |---|---|
 | validates + flattens every locale before registering any | a malformed catalog fails the boot whole, never half |
-| registers the framework catalog first, the app's second | later wins, so app strings override framework strings |
+| registers the framework catalog under `en` first, the app's second | later wins, so app strings override framework strings |
 | `configureLocales({ supported, fallback })` | the locale set is declared once, not twice |
 | returns `{ default, locales, catalogs, keys() }` | the app's key space, for tests and tooling |
 
@@ -90,6 +90,13 @@ wins, which is how an app overrides `errors.notFound.title` without forking the
 `src/catalogs/en.json` ships the framework's own strings: `errors.*`, `auth.*`,
 `pagination.*`, `admin.*`, `validation.*`, `common.*`, `time.cron.*`.
 
+**It is registered under `en` and no other locale** — the golden rule applies to framework strings
+too. An app shipping `es` that has not translated `errors.notFound.title` renders
+`⟦errors.notFound.title⟧` there, not `Page not found`: filling every locale with the English
+catalog is a fallback chain, it reads as `isMiss === false`, and `assertCatalogsComplete` cannot
+see it because `CatalogSet.catalogs` carries app strings only. Translate the framework keys your
+app renders into your own catalog — that is the one path, and it is the same merge an override is.
+
 ## Enforcement
 
 `extractKeys()` scans source for `t('...')` calls; `auditCatalogs()` reports keys used,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Dependency-free translator, catalog flattening, locale negotiation and loud missing-key rendering",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "3.0.0"
+    "@ultimat3/core": "4.0.0"
   }
 }

package/src/context.ts

@@ -19,15 +19,22 @@ import { createTranslator, type TranslateVars, type Translator } from './transla
 /** The cookie an explicit language switcher writes. */
 export const LOCALE_COOKIE = 'x_locale';
 
+/**
+ * Every source is `string | null | undefined`. Not decoration: `exactOptionalPropertyTypes` is on,
+ * so `?: string | null` refuses an EXPLICIT `undefined` — and `localeCookieOf`, this file's own
+ * cookie reader, answers `string | undefined`, so `resolveLocale({ cookie: localeCookieOf(h) })`
+ * (the composition the package exists to offer) did not typecheck. `resolveLocale` has skipped
+ * `undefined` since it was written; only the declaration disagreed.
+ */
 export interface LocaleSources {
   /** Raw `Accept-Language` header value. */
-  header?: string | null;
+  header?: string | null | undefined;
   /** Value of the `x_locale` cookie, already URL-decoded. */
-  cookie?: string | null;
+  cookie?: string | null | undefined;
   /** `user.locale` from the authenticated user record. */
-  user?: string | null;
+  user?: string | null | undefined;
   /** `?locale=es` — mobile and email preview links pass it per request. */
-  query?: string | null;
+  query?: string | null | undefined;
 }
 
 export type LocaleSourceName = keyof LocaleSources;
@@ -54,12 +61,30 @@ export interface LocaleConfig {
  */
 const DEFAULT_ORDER: readonly LocaleSourceName[] = ['query', 'cookie', 'user', 'header'];
 
-let config: LocaleConfig = {
+/** Hoisted so `resetLocaleConfig` has one value to name, rather than a second literal to drift. */
+const DEFAULT_LOCALE_CONFIG: LocaleConfig = {
   supported: SUPPORTED_LOCALES,
   fallback: DEFAULT_LOCALE,
   order: DEFAULT_ORDER,
 };
 
+/**
+ * A fresh object AND fresh arrays, every time. Handing out `DEFAULT_LOCALE_CONFIG` itself made the
+ * live config the shipped default, so one caller writing through `localeConfig()` corrupted the
+ * value `resetLocaleConfig()` restores FROM — and the reset replayed the corruption for the rest of
+ * the process. `readonly` in the type stops a compiler, not a caller, and this seam exists because
+ * callers do what the types did not expect.
+ */
+function freshDefaultConfig(): LocaleConfig {
+  return {
+    supported: [...DEFAULT_LOCALE_CONFIG.supported],
+    fallback: DEFAULT_LOCALE_CONFIG.fallback,
+    order: [...DEFAULT_LOCALE_CONFIG.order],
+  };
+}
+
+let config: LocaleConfig = freshDefaultConfig();
+
 /** Called once at boot from `app.config.ts`. */
 export function configureLocales(partial: Partial<LocaleConfig>): LocaleConfig {
   config = { ...config, ...partial };
@@ -120,7 +145,12 @@ export function localeCookieOf(cookieHeader?: string | null): string | undefined
  */
 export function currentLocale(): Locale {
   const locale = tryUseContext()?.locale;
-  return locale === undefined || locale === '' ? config.fallback : locale;
+  if (locale === undefined || locale === '') return config.fallback;
+  // Normalised HERE, the same call `resolveLocale` makes for every source it reads. `Ctx.locale`
+  // is a plain string core never validates, and every distinct one it holds bought a PERMANENT
+  // `Translator` in `translators` plus a permanent `Intl.PluralRules` in `interpolate`'s
+  // `rulesCache` — two unbounded module-level maps keyed by whatever a request carried.
+  return normalizeLocale(locale, config.supported, config.fallback);
 }
 
 export function currentDirection(): Direction {
@@ -140,6 +170,15 @@ export function registerCatalog(locale: Locale, catalog: Catalog): void {
   translators.delete(locale);
 }
 
+/**
+ * Whether this locale has a catalog at all. Distinct from `catalogFor`, which answers `{}` for
+ * "registered but empty" and for "never registered" alike — `registerFrameworkCatalog` needs to
+ * tell those apart to stay idempotent.
+ */
+export function hasCatalog(locale: Locale): boolean {
+  return registry.has(locale);
+}
+
 export function registeredLocales(): Locale[] {
   return [...registry.keys()].sort();
 }
@@ -173,6 +212,19 @@ export function t(key: string, vars?: TranslateVars): string {
   return useI18n()(key, vars);
 }
 
+/**
+ * Test/CLI seam: back to the shipped supported set, fallback and precedence.
+ *
+ * `defineCatalogs()` calls `configureLocales()` at an APP's module scope, and a module evaluates
+ * once per `bun test` process — so one file that loads an app narrows `supported` for every file
+ * after it, and `Accept-Language: de-DE` negotiates `en` in a file that never mentioned locales.
+ * `configureLocales` MERGES, so no partial call can widen the set back; only a value the framework
+ * owns can, which is why this is a reset and not a documented "remember to restore it".
+ */
+export function resetLocaleConfig(): void {
+  config = freshDefaultConfig();
+}
+
 /** Test/CLI seam: drop every registered catalog. */
 export function resetCatalogs(): void {
   registry.clear();

package/src/define-catalogs.ts

@@ -38,10 +38,13 @@ export function defineCatalogs<TLocales extends CatalogSources>(
   // whole, not leave half the locales live and the other half missing.
   const loaded = locales.map((locale) => [locale, loadCatalog(input.locales[locale])] as const);
 
+  // Framework first, app second. `registerCatalog` merges and the later call wins, which is how an
+  // app overrides `errors.notFound.title` without forking the framework catalog. ONCE, not once
+  // per locale: the framework catalog is English, and registering it under every locale filled
+  // `es` with English for every key the app had not translated — `isMiss` false, gap invisible,
+  // the exact fallback chain `⟦key⟧` exists to refuse.
+  registerFrameworkCatalog();
   for (const [locale, catalog] of loaded) {
-    // Framework first, app second. `registerCatalog` merges and the later call wins, which is
-    // how an app overrides `errors.notFound.title` without forking the framework catalog.
-    registerFrameworkCatalog(locale);
     registerCatalog(locale, catalog);
   }
   configureLocales({ supported: locales, fallback: input.default });

package/src/framework.ts

@@ -5,7 +5,7 @@
 
 import { type Catalog, loadCatalog } from './catalog';
 import en from './catalogs/en.json';
-import { registerCatalog } from './context';
+import { hasCatalog, registerCatalog } from './context';
 import { DEFAULT_LOCALE, type Locale } from './locales';
 
 /**
@@ -19,7 +19,23 @@ export const FRAMEWORK_CATALOG: Catalog = loadCatalog(en);
 
 export const FRAMEWORK_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
 
-/** Called by the HTTP layer at boot. Idempotent. */
-export function registerFrameworkCatalog(locale: Locale = FRAMEWORK_CATALOG_LOCALE): void {
-  registerCatalog(locale, FRAMEWORK_CATALOG);
+/**
+ * Register the framework's own strings under the ONE locale they are written in.
+ *
+ * **No locale parameter, and that is the fix**: this catalog is English, so registering it under
+ * `es` was a fallback chain with no name. An app shipping only `es` served `Page not found` and
+ * English `ui.*` chrome with `isMiss` reading FALSE, so nothing downstream could see the gap —
+ * the one thing `⟦key⟧` exists to make impossible. A locale argument is now a compile error.
+ *
+ * **Idempotent by construction, not by comment**: a locale that already has a catalog is left
+ * alone. `registerCatalog` merges the existing entry FIRST and its argument second, so a second
+ * call after an app registered put the English string back on top of every framework key that app
+ * had overridden — silently, and only for the keys it cared enough to translate.
+ *
+ * `defineCatalogs` is the only production caller; the export exists for boot code that cannot
+ * know whether an app has registered yet, which is exactly the call this guard makes safe.
+ */
+export function registerFrameworkCatalog(): void {
+  if (hasCatalog(FRAMEWORK_CATALOG_LOCALE)) return;
+  registerCatalog(FRAMEWORK_CATALOG_LOCALE, FRAMEWORK_CATALOG);
 }

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   registerCatalog,
   registeredLocales,
   resetCatalogs,
+  resetLocaleConfig,
   resolveLocale,
   t,
   translatorFor,