@ultimat3/i18n 7.0.0 → 8.0.0

package/CLAUDE.md

@@ -67,6 +67,25 @@ Imported by every package that renders a string.
   travels as data (`t(row.labelKey)`). Both halves are load-bearing: the guard in `translator.ts`
   makes it true of a catalog this package did not build, the null prototype makes `__proto__` an
   ordinary key instead of one the setter silently swallows. Never reintroduce either.
+- **Both module-level caches are bounded and canonically keyed, through `@ultimat3/core`'s
+  `cachedFormatter` / `canonicalLocale`** — `context.ts`'s `translators` and `interpolate.ts`'s
+  `rulesCache`. `translatorFor` and `pluralCategory` are exported raw and `@ultimat3/mail` passes
+  an unnormalised value, so the key is a REQUEST value: keyed raw into an unbounded `Map`, 5,000
+  distinct-but-valid tags retained +108 MB after `Bun.gc(true)`, against +11 MB bounded. The bound
+  and the canonical key are two halves of ONE rule — `en-us` and `en-US` must not each buy an
+  entry, or the cap counts spellings instead of locales. Never re-key either map on the raw tag;
+  `context.test.ts`'s `the translator cache` and `interpolate.test.ts`'s `the plural-rules cache`
+  are what notice.
+- **A tag `canonicalLocale` REFUSES shares one key, and `translatorFor` resolves the catalog
+  through that key.** Two holes in the rule above, both reachable from a header. `?? locale` put a
+  malformed tag back in as its own key, so a bounded cache was still one a client could flush —
+  they collapse onto `INVALID_LOCALE_KEY` (`rulesCache`: onto `en`, which is what they render as
+  anyway), and a REGISTERED tag ICU will not canonicalise is the one exception, keying on itself.
+  And `registry.has(locale) ? locale : key` read the registry under two spellings but never the
+  registered one: `registerCatalog('en-US', …)` then `translatorFor('en-us')` matched neither, so it
+  cached an EMPTY translator under `en-us` and the later `translatorFor('en-US')` was served it.
+  `registeredUnder` is what makes the catalog independent of which spelling arrived first — resolve
+  BEFORE `cachedFormatter`, never inside the branch that already missed.
 - Plural selection is `Intl.PluralRules`. Never `count === 1`. Variants are underscore suffixes on
   the leaf — a CLDR category (`_zero _one _two _few _many _other`), or `n` / `n_plural` as the
   two-form shortcut; pair `n_one` with `n_other`, never with `n_plural`. Never a nested

package/package.json

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

package/src/context.ts

@@ -3,7 +3,7 @@
  * No call site passes a locale by hand — `t()` here is the ambient translator.
  */
 
-import { tryUseContext } from '@ultimat3/core';
+import { cachedFormatter, canonicalLocale, tryUseContext } from '@ultimat3/core';
 import { type Catalog, mergeCatalogs } from './catalog';
 import {
   DEFAULT_LOCALE,
@@ -147,9 +147,10 @@ export function currentLocale(): Locale {
   const locale = tryUseContext()?.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.
+  // is a plain string core never validates, so this is the step that keeps a request's own
+  // spelling out of the catalog lookup entirely. `translators` and `interpolate`'s `rulesCache`
+  // are bounded now and no longer grow with it — but a bound EVICTS, and an ambient locale an app
+  // never registered would still answer every key with a loud miss.
   return normalizeLocale(locale, config.supported, config.fallback);
 }
 
@@ -158,7 +159,55 @@ export function currentDirection(): Direction {
 }
 
 const registry = new Map<Locale, Catalog>();
-const translators = new Map<Locale, Translator>();
+const translators = new Map<string, Translator>();
+
+/**
+ * The one key every unregistered tag that is not a locale at all shares. A `Symbol` cannot be a
+ * `Map<string, …>` key and a NUL cannot appear in a structurally valid tag, so nothing a caller
+ * sends can collide with it.
+ */
+const INVALID_LOCALE_KEY = '\u0000invalid';
+
+/**
+ * The one key `translatorFor` caches under and every registration evicts by.
+ *
+ * `translatorFor` is exported raw and `packages/mail/src/render.ts` hands it a value nothing
+ * normalised, so this map was keyed on whatever spelling a request carried — permanently, and
+ * `en-us` and `en-US` bought two `Translator`s for one locale. Canonicalising is what makes
+ * `cachedFormatter`'s bound a bound on LOCALES rather than on spellings; lowercasing is what keeps
+ * the key equal to the one an app registered (`zh-hant`, never ICU's `zh-Hant`), so a later
+ * `registerCatalog` still drops the entry a request built.
+ *
+ * A tag `canonicalLocale` refuses (`en_US`, `''`, `not a locale`) is not a spelling of anything, so
+ * it collapses onto ONE key rather than keying on itself: a bound that a request value can key into
+ * counts junk against the cap and evicts locales that are real. Registered spellings are the
+ * exception and key on themselves — an app that registered a tag ICU will not canonicalise must
+ * still be handed its own catalog, and `registerCatalog` stores before it evicts, so both sides of
+ * that decision read the same registry.
+ */
+function translatorKey(locale: Locale): string {
+  const canonical = canonicalLocale(locale);
+  if (canonical !== undefined) return canonical.toLowerCase();
+  return registry.has(locale) ? locale.toLowerCase() : INVALID_LOCALE_KEY;
+}
+
+/**
+ * The registered spelling `key` stands for, or `undefined` when no catalog was registered for it.
+ *
+ * The caller's own spelling wins when it was registered, so an app that registered `en` keeps
+ * answering `en`. Otherwise the registry is read through the SAME canonical key the cache is
+ * keyed by: `registerCatalog('en-US', …)` followed by `translatorFor('en-us')` matched neither
+ * `registry.has(locale)` nor `catalogFor(key)`, so it cached an EMPTY translator under `en-us` —
+ * and the later `translatorFor('en-US')` was served that same empty translator from the cache.
+ * Which of the two spellings a request carried first decided whether the app's strings rendered.
+ */
+function registeredUnder(locale: Locale, key: string): Locale | undefined {
+  if (registry.has(locale)) return locale;
+  for (const registered of registry.keys()) {
+    if (translatorKey(registered) === key) return registered;
+  }
+  return undefined;
+}
 
 /**
  * The layer under every app catalog: strings this framework ships and no app can be asked to
@@ -197,7 +246,7 @@ function installBase(): void {
   for (const [locale, catalog] of base) {
     const existing = registry.get(locale);
     registry.set(locale, existing === undefined ? catalog : mergeCatalogs(catalog, existing));
-    translators.delete(locale);
+    translators.delete(translatorKey(locale));
   }
 }
 
@@ -208,7 +257,7 @@ function installBase(): void {
 export function registerCatalog(locale: Locale, catalog: Catalog): void {
   const existing = registry.get(locale);
   registry.set(locale, existing === undefined ? catalog : mergeCatalogs(existing, catalog));
-  translators.delete(locale);
+  translators.delete(translatorKey(locale));
 }
 
 export function registeredLocales(): Locale[] {
@@ -224,11 +273,13 @@ export function catalogFor(locale: Locale): Catalog {
  * `TCatalog` narrows the key type only; the runtime catalog is whatever is registered.
  */
 export function translatorFor<TCatalog = Catalog>(locale: Locale): Translator<TCatalog> {
-  let translator = translators.get(locale);
-  if (translator === undefined) {
-    translator = createTranslator(catalogFor(locale), locale);
-    translators.set(locale, translator);
-  }
+  const key = translatorKey(locale);
+  // Resolved BEFORE the memo, so what lands under `key` is the catalog that key stands for and
+  // not whichever spelling asked first. The caller's own tag reaches `createTranslator` either
+  // way — the catalog is chosen by locale, the formatting by what the caller actually sent.
+  const translator = cachedFormatter(translators, key, () =>
+    createTranslator(catalogFor(registeredUnder(locale, key) ?? locale), locale),
+  );
   // One cast, one place. `TCatalog` narrows the key parameter and nothing else, so the memoized
   // object already is the right value — the registry cannot be keyed by an app's catalog type.
   return translator as unknown as Translator<TCatalog>;

package/src/errors.ts

@@ -57,7 +57,7 @@ export function catalogMissingKeys(locale: string, keys: readonly string[]): I18
   return new I18nError({
     code: 'X_CATALOG_MISSING_KEYS',
     cause: `packages/i18n/catalogs/${locale}.json is missing ${keys.length} key(s) used in source: ${shown.join(', ')}${suffix}`,
-    fix: `x i18n sync ${locale}`,
+    fix: `x i18n sync ${locale}   # writes each key above as ⟦key⟧ — replace every one with the real string`,
   });
 }
 

package/src/interpolate.ts

@@ -3,6 +3,8 @@
  * Pure string work: it never reads a catalog and never resolves a locale.
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
+
 export type InterpolationValue = string | number | boolean;
 export type InterpolationVars = Record<string, InterpolationValue>;
 
@@ -108,16 +110,25 @@ export function pluralVariantsOf(key: string): string[] {
 
 const rulesCache = new Map<string, Intl.PluralRules>();
 
+/**
+ * Bounded and canonically keyed, because `locale` reaches here from an `Accept-Language` header
+ * through `t()`. Keyed raw into an unbounded `Map`, every distinct spelling a client sent bought a
+ * PERMANENT `Intl.PluralRules` — memory the client chooses. `canonicalLocale` collapses `EN-us`
+ * and `en-US` onto one key and `cachedFormatter` caps the rest; neither half is sufficient alone,
+ * which is why both come from the one place `@ultimat3/money` and `@ultimat3/time` read them from.
+ */
 function pluralRulesFor(locale: string): Intl.PluralRules {
-  const cached = rulesCache.get(locale);
-  if (cached !== undefined) return cached;
-  // An unknown tag would throw inside Intl; degrade to `en` rather than break a render.
-  let rules: Intl.PluralRules;
-  try {
-    rules = new Intl.PluralRules(locale);
-  } catch {
-    rules = new Intl.PluralRules('en');
-  }
-  rulesCache.set(locale, rules);
-  return rules;
+  // The canonical tag is the key AND what reaches `Intl`, so the rules a key answers with never
+  // depend on which spelling of it arrived first. A tag `canonicalLocale` refuses is not a locale
+  // at all and this function already degrades to English for it — so `en` is the key too, rather
+  // than one bounded slot per junk string a client chose to send.
+  const tag = canonicalLocale(locale) ?? 'en';
+  return cachedFormatter(rulesCache, tag, () => {
+    try {
+      return new Intl.PluralRules(tag);
+    } catch {
+      // An unknown tag would throw inside Intl; degrade to `en` rather than break a render.
+      return new Intl.PluralRules('en');
+    }
+  });
 }