@ultimat3/i18n 5.0.1 → 6.0.0

package/CLAUDE.md

@@ -12,7 +12,9 @@ Imported by every package that renders a string.
 | `define-catalogs.ts` | the app's one registration call. Boot only, composes the four below. |
 | `interpolate.ts` | `{var}` + CLDR plural selection. No catalog access (takes a `has` predicate). |
 | `locales.ts` | supported set, normalize, negotiate, RTL. No catalogs. |
-| `context.ts` | request locale via ALS, the registry, the ambient `t` and `useI18n`. |
+| `context.ts` | request locale via ALS, the registry + the base layer under it, the ambient `t` and `useI18n`. |
+| `framework.ts` | the framework's own strings, installed as the base layer at module scope. |
+| `registration.ts` | are the catalogs an app SHIPS in the registry it READS? No file access. |
 | `extract.ts` | static scan + audit for `x verify`. |
 | `catalogs/en.json` | data, not code. |
 
@@ -28,13 +30,29 @@ Imported by every package that renders a string.
   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.
+- **`FRAMEWORK_CATALOG` is the base layer**, installed by `framework.ts` at module scope —
+  importing `@ultimat3/i18n` is what registers it, so no app can forget it and `resetCatalogs()`
+  puts it back. It was `registerFrameworkCatalog()`, whose ONE caller was `defineCatalogs`, so an
+  app whose catalog module nothing imported served `⟦errors.notFound.title⟧` on its 404 page and
+  `⟦ui.*⟧` in every design-system control, with `x verify` green (issue #249). Under
+  `FRAMEWORK_CATALOG_LOCALE` (`en`) **only**: it ran per locale until 2026-08, so an `es`-only app
+  served `Page not found` with `isMiss` reading FALSE — the fallback chain the line above refuses,
+  wearing registration as a disguise. A non-`en` app translates the framework keys it renders into
+  its own catalog.
+- **The base layer merges UNDER whatever `registerCatalog` seated, never over it**, so an app's
+  override of a framework key survives every later install and the install is idempotent by
+  construction rather than by a module flag `resetCatalogs()` would go stale against.
+  `registerBaseCatalog` is **framework packages only** — `@ultimat3/mail` calls it for `mail.*`,
+  which had the identical defect and the identical fix. It is not a second app path: everything
+  installed there loses to `registerCatalog` on the same key, so the strongest thing an app could
+  achieve by calling it is strings its own `defineCatalogs()` overrides. That the rule is
+  documented and not a build error is the one hole in this file; closing it is a `boundaries` rule
+  refusing the specifier outside `packages/*/src`.
+- **A catalog on disk is not a registered catalog.** `catalogRegistrationGaps` /
+  `assertCatalogsRegistered` answer the runtime question per locale — `X_CATALOG_UNREGISTERED` —
+  and `x verify`'s `i18n` step is what asks it of an app. An app reads strings through its OWN
+  module (`useT()` from `packages/i18n/src/index.ts`), never `t` from `@ultimat3/i18n`, so that
+  registration is a consequence of rendering rather than something a boot has to remember.
 - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "5.0.1",
+  "version": "6.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": "5.0.1"
+    "@ultimat3/core": "6.0.0"
   }
 }

package/src/context.ts

@@ -161,22 +161,54 @@ const registry = new Map<Locale, Catalog>();
 const translators = new Map<Locale, Translator>();
 
 /**
- * Register a locale's catalog. Called with the framework catalog first and the app
- * catalog second so app strings override framework strings for the same key.
+ * The layer under every app catalog: strings this framework ships and no app can be asked to
+ * register. `framework.ts` installs its own at module scope, so importing `@ultimat3/i18n` at all
+ * is what puts `errors.*`, `auth.*` and `ui.*` in the registry — an app that never reaches
+ * `defineCatalogs()` still renders a 404 page in words, not in `⟦errors.notFound.title⟧`.
+ * Kept apart from `registry` for one reason: `resetCatalogs()` must be able to drop everything an
+ * app registered WITHOUT dropping strings the framework itself renders.
  */
-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);
+const base = new Map<Locale, Catalog>();
+
+/**
+ * Install a base layer. **Framework packages only** — a package whose own templates render strings
+ * an app never registers (`@ultimat3/mail`'s `mail.*`) calls this at module scope, so importing it
+ * is what installs them. An app has exactly one registration call, `defineCatalogs`, and this is
+ * not a second one: everything installed here loses to `registerCatalog` on the same key, so the
+ * strongest thing an app could achieve by calling it is strings that its own catalog overrides.
+ *
+ * More than one framework contributor is merged into the base itself rather than fighting over the
+ * locale, so a package whose strings arrive later cannot displace `framework.ts`'s.
+ */
+export function registerBaseCatalog(locale: Locale, catalog: Catalog): void {
+  const existing = base.get(locale);
+  base.set(locale, existing === undefined ? catalog : mergeCatalogs(existing, catalog));
+  installBase();
+}
+
+/**
+ * Base UNDER app, never over it — `mergeCatalogs` takes the later argument, so the registered
+ * catalog goes second and an app's override of `errors.notFound.title` survives every install.
+ * Merging rather than skipping an occupied locale is what makes this order-independent: a base
+ * registered after an app's `defineCatalogs()` still lands, and a repeat is a no-op because the
+ * app's value already won the same key.
+ */
+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);
+  }
 }
 
 /**
- * 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.
+ * Register a locale's catalog. App strings arrive here and override the base layer for the same
+ * key, because the merge takes the argument last.
  */
-export function hasCatalog(locale: Locale): boolean {
-  return registry.has(locale);
+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);
 }
 
 export function registeredLocales(): Locale[] {
@@ -225,8 +257,15 @@ export function resetLocaleConfig(): void {
   config = freshDefaultConfig();
 }
 
-/** Test/CLI seam: drop every registered catalog. */
+/**
+ * Test/CLI seam: drop every catalog an APP registered, and put the base layer back.
+ *
+ * Not a full clear: the framework's own strings are installed by importing this package, once per
+ * process, so a clear that took them out could never restore them — every test after the first
+ * reset rendered `⟦errors.notFound.title⟧` for a string no app owns.
+ */
 export function resetCatalogs(): void {
   registry.clear();
   translators.clear();
+  installBase();
 }

package/src/define-catalogs.ts

@@ -7,7 +7,6 @@
 import { type Catalog, catalogKeys, loadCatalog, mergeCatalogs } from './catalog';
 import { configureLocales, registerCatalog } from './context';
 import { localeUnsupported } from './errors';
-import { registerFrameworkCatalog } from './framework';
 
 /** Locale tag → the catalog file's parsed contents, nested exactly as authored. */
 export type CatalogSources = Readonly<Record<string, unknown>>;
@@ -38,12 +37,9 @@ 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();
+  // No framework-catalog call here, and that is deliberate: `framework.ts` installs it as the base
+  // layer at package import, so it is already under this app's strings whether or not THIS module
+  // ever runs. `registerCatalog` merges its argument last, so app strings still win the same keys.
   for (const [locale, catalog] of loaded) {
     registerCatalog(locale, catalog);
   }

package/src/errors.ts

@@ -9,6 +9,7 @@ export const I18N_ERROR_CODES = [
   'X_LOCALE_UNSUPPORTED',
   'X_CATALOG_MISSING_KEYS',
   'X_CATALOG_INVALID',
+  'X_CATALOG_UNREGISTERED',
 ] as const;
 
 export type I18nErrorCode = (typeof I18N_ERROR_CODES)[number];
@@ -17,6 +18,7 @@ export const I18N_ERROR_TITLES: Readonly<Record<I18nErrorCode, string>> = {
   X_LOCALE_UNSUPPORTED: 'locale is not in the supported set',
   X_CATALOG_MISSING_KEYS: 'a catalog is missing keys used in source',
   X_CATALOG_INVALID: 'a catalog entry is malformed',
+  X_CATALOG_UNREGISTERED: 'a shipped catalog never reached the runtime registry',
 };
 
 // Titles must be registered for format() to render the contract's first line. Every code above is
@@ -59,6 +61,55 @@ export function catalogMissingKeys(locale: string, keys: readonly string[]): I18
   });
 }
 
+/**
+ * The keys, capped and comma-joined. Shared by both factories below because a `fix:` an agent can
+ * act on has to name keys, and a 300-key catalog rendered whole is a cause nobody reads.
+ */
+function shownKeys(keys: readonly string[]): string {
+  const shown = keys.slice(0, 8);
+  const suffix = keys.length > shown.length ? `, +${keys.length - shown.length} more` : '';
+  return `${shown.join(', ')}${suffix}`;
+}
+
+/**
+ * The fix is an EDIT, not a command, because no command can wire an import: registration is a side
+ * effect of importing the module that calls `defineCatalogs()`, and the boot loads app modules by
+ * scanning `packages/<pkg>/src` and `apps/<app>/{site,app,api,shared}` — a catalog module outside
+ * that tree is never imported, and `x verify` stays green while every string renders a loud miss.
+ */
+const REGISTRATION_FIX =
+  'move the defineCatalogs() call into packages/i18n/src/index.ts (where `x new` puts it, inside the boot scan) and read strings through its useT(), never `t` from @ultimat3/i18n; then re-run: x i18n check --json';
+
+/**
+ * A catalog the app ships that the running app cannot answer from. Issue #249: the file was on
+ * disk, its keys were used in source, `x i18n check` and `x verify` were both green, and every
+ * page rendered `⟦key⟧` because nothing had imported the module that registers it.
+ */
+export function catalogUnregistered(input: {
+  locale: string;
+  shipped: number;
+  missing: readonly string[];
+}): I18nError {
+  return new I18nError({
+    code: 'X_CATALOG_UNREGISTERED',
+    cause: `packages/i18n/catalogs/${input.locale}.json defines ${input.shipped} key(s) and ${input.missing.length} of them are not in the runtime registry after the app's own modules loaded: ${shownKeys(input.missing)} — each renders \u27e6key\u27e7`,
+    fix: REGISTRATION_FIX,
+  });
+}
+
+/**
+ * The same failure with nothing on disk to name: source calls `t()` and no catalog anywhere
+ * answers. Distinct cause, same code and same fix — an audit that compared a missing file against
+ * a missing catalog reported "no gaps", which is the vacuous green this code exists to refuse.
+ */
+export function catalogsNeverRegistered(locale: string, unresolved: readonly string[]): I18nError {
+  return new I18nError({
+    code: 'X_CATALOG_UNREGISTERED',
+    cause: `no catalog is registered for "${locale}" and ${unresolved.length} key(s) used in source resolve to nothing: ${shownKeys(unresolved)} — each renders \u27e6key\u27e7`,
+    fix: `x i18n add ${locale}   # then ${REGISTRATION_FIX}`.trim(),
+  });
+}
+
 export function catalogInvalid(path: string, cause: string): I18nError {
   return new I18nError({
     code: 'X_CATALOG_INVALID',

package/src/framework.ts

@@ -1,11 +1,11 @@
 /**
- * The framework's own strings, flattened once at import.
- * Register these before app catalogs so an app can override any framework key.
+ * The framework's own strings, flattened and installed as the base layer at import.
+ * Under every app catalog, so an app overrides any framework key and forgets none.
  */
 
 import { type Catalog, loadCatalog } from './catalog';
 import en from './catalogs/en.json';
-import { hasCatalog, registerCatalog } from './context';
+import { registerBaseCatalog } from './context';
 import { DEFAULT_LOCALE, type Locale } from './locales';
 
 /**
@@ -17,25 +17,20 @@ import { DEFAULT_LOCALE, type Locale } from './locales';
  */
 export const FRAMEWORK_CATALOG: Catalog = loadCatalog(en);
 
-export const FRAMEWORK_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
-
 /**
- * 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.
+ * The ONE locale this catalog is written in.
  *
- * **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.
+ * Registering it under every locale 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 non-`en` app
+ * translates the framework keys it renders into its own catalog.
  */
-export function registerFrameworkCatalog(): void {
-  if (hasCatalog(FRAMEWORK_CATALOG_LOCALE)) return;
-  registerCatalog(FRAMEWORK_CATALOG_LOCALE, FRAMEWORK_CATALOG);
-}
+export const FRAMEWORK_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
+
+// At module scope, and that is the whole point: `index.ts` re-exports this file, so anything that
+// can call `t()` has already imported the module that installs these strings. It was a function
+// (`registerFrameworkCatalog`) that only `defineCatalogs` called until 5.1.0 — so an app whose
+// catalog module nothing imported rendered `⟦errors.notFound.title⟧` on its 404 page, `⟦ui.*⟧` in
+// every design-system control, and had no way to notice (issue #249). Registration that an app
+// can forget is not registration; the framework's half of it is now unforgettable by construction.
+registerBaseCatalog(FRAMEWORK_CATALOG_LOCALE, FRAMEWORK_CATALOG);

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   type LocaleSources,
   localeConfig,
   localeCookieOf,
+  registerBaseCatalog,
   registerCatalog,
   registeredLocales,
   resetCatalogs,
@@ -41,6 +42,8 @@ export {
 export {
   catalogInvalid,
   catalogMissingKeys,
+  catalogsNeverRegistered,
+  catalogUnregistered,
   I18N_ERROR_CODES,
   I18N_ERROR_TITLES,
   I18nError,
@@ -61,11 +64,7 @@ export {
   type LocaleAudit,
   mergeExtractions,
 } from './extract';
-export {
-  FRAMEWORK_CATALOG,
-  FRAMEWORK_CATALOG_LOCALE,
-  registerFrameworkCatalog,
-} from './framework';
+export { FRAMEWORK_CATALOG, FRAMEWORK_CATALOG_LOCALE } from './framework';
 export {
   type InterpolationValue,
   type InterpolationVars,
@@ -91,6 +90,11 @@ export {
   parseAcceptLanguage,
   SUPPORTED_LOCALES,
 } from './locales';
+export {
+  assertCatalogsRegistered,
+  type CatalogRegistrationGap,
+  catalogRegistrationGaps,
+} from './registration';
 export {
   createTranslator,
   isMiss,

package/src/registration.ts

@@ -0,0 +1,49 @@
+// Whether the catalogs an app SHIPS are the catalogs the running app READS. The audit in
+// `extract.ts` compares source against files on disk and can be green while the registry is empty
+// (issue #249) — registration is a side effect of importing a module, so only the registry knows.
+
+import { type Catalog, missingFrom } from './catalog';
+import { catalogFor } from './context';
+import { catalogUnregistered } from './errors';
+import type { Locale } from './locales';
+
+/** One locale's shipped catalog measured against the registry the running app reads. */
+export interface CatalogRegistrationGap {
+  readonly locale: Locale;
+  /** How many keys the shipped catalog defines — the denominator the cause reports against. */
+  readonly shipped: number;
+  /** Shipped keys the registry cannot answer, sorted. Every one renders a loud miss. */
+  readonly missing: readonly string[];
+}
+
+/**
+ * Per locale, because the registry is: a key registered under `en` does not answer a request that
+ * resolved to `es`, and a set-of-all-keys check would call an `es`-only app wired.
+ *
+ * The caller supplies what the app ships — the parsed `packages/i18n/catalogs/*.json` for a CLI
+ * check, `CatalogSet.catalogs` for a boot assertion. This package never reads a file.
+ */
+export function catalogRegistrationGaps(
+  shipped: Readonly<Record<Locale, Catalog>>,
+): readonly CatalogRegistrationGap[] {
+  const gaps: CatalogRegistrationGap[] = [];
+  for (const locale of Object.keys(shipped).sort()) {
+    const catalog = shipped[locale];
+    if (catalog === undefined) continue;
+    const missing = missingFrom(catalog, catalogFor(locale));
+    if (missing.length === 0) continue;
+    gaps.push({ locale, shipped: Object.keys(catalog).length, missing });
+  }
+  return gaps;
+}
+
+/**
+ * The boot-time half: throw on the first locale that did not reach the registry. One locale per
+ * throw and not a joined summary, because the `fix:` is the same edit for all of them and a cause
+ * naming five locales is one nobody reads to the end.
+ */
+export function assertCatalogsRegistered(shipped: Readonly<Record<Locale, Catalog>>): void {
+  const gap = catalogRegistrationGaps(shipped)[0];
+  if (gap === undefined) return;
+  throw catalogUnregistered(gap);
+}