@ultimat3/i18n 1.2.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,64 @@
+# @ultimat3/i18n — agent notes
+
+**Tier 1.** May import `@ultimat3/core`, `@ultimat3/schema`. Nothing else, no external deps.
+Imported by every package that renders a string.
+
+## Boundary
+
+| File | Single responsibility |
+|---|---|
+| `translator.ts` | lookup + delegate interpolation, and `TranslationKey`. No locale logic. |
+| `catalog.ts` | nested → flat, merge, validate. No lookup. |
+| `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`. |
+| `extract.ts` | static scan + audit for `x verify`. |
+| `catalogs/en.json` | data, not code. |
+
+## Rules
+
+- An app registers catalogs with `defineCatalogs({ default, locales })`. One call, at boot.
+  `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.
+- A miss renders `⟦key⟧`. Never add a fallback locale chain — it hides gaps.
+- 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
+  for. Same reach `catalog.ts` shuts off by nesting into null-prototype nodes; never reintroduce
+  either. The `interpolate` fast path must test **both** braces: `}}` un-escapes with no `{` in
+  sight, and a `{`-only check gave one escape two meanings.
+- 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
+  `{ one, other }` branch — the runtime probes the variant leaf (`n_other`), and `TranslationKey`
+  admits the stem `n` on exactly that basis.
+- `Translator<TCatalog = Catalog>` must keep defaulting to `string` keys: `@ultimat3/ui` and
+  `@ultimat3/mail` take a bare `Translator`. `has()` and `raw()` stay `string` — they are probes.
+- Nothing here formats a number, date or money. That is `@ultimat3/money` / `@ultimat3/time`.
+- **The ambient locale IS `Ctx.locale`**, core's own declared field — this package writes no context
+  field of its own and publishes no writer. `createContext({ locale })` and
+  `withChildContext({ locale })` are the only ways in, `currentLocale()` the only way out.
+  `attachLocale`/`localeOf` existed until 1.3.0 with zero callers; `@ultimat3/time` had the same
+  pair over a field name (`ctx['timeZone']`) that disagreed with core's `tz`, which is what made
+  every server-rendered date UTC. Never reintroduce either half.
+- Adding a framework string: `catalogs/en.json`, feature-namespaced, then use `t('ns.key')`.
+- **`catalogs/en.json` is gated in both directions**, on `x verify`'s `boundaries` step via
+  `scripts/i18n-catalog.ts`. A `t('literal')` in `packages/*/src` with no entry is
+  `X_CATALOG_MISSING_KEYS`; an entry nothing in framework source names, in a namespace the
+  framework already renders (`admin.*`, `dev.*`, `ui.*`), is `X_CATALOG_KEY_UNREACHABLE`. The
+  namespaces the framework only *ships* for an app (`common.*`, `auth.*`, `errors.*`,
+  `pagination.*`, `validation.*`, `time.*`) are exempt from the second half and derived, not
+  listed. `ui.*` is pinned exactly by `packages/ui/src/i18n-keys.test.ts`, because every ui string
+  resolves as `ui.t(UI_KEYS.x)` and no static scan can follow that.
+- A name is a **leaf or a branch, never both** — `parseNestedCatalog` refuses a dot inside a key,
+  so `admin.detail.not-found` and `admin.detail.not-found.fix` cannot coexist. Both keys shipped
+  and neither was in the catalog; the leaf is now `…not-found.cause`.
+
+## Commands
+
+```
+bun test packages/i18n
+bun run --filter @ultimat3/i18n typecheck
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Dependency-free translator, catalog flattening, locale negotiation and loud missing-key rendering",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0"
+    "@ultimat3/core": "2.0.0"
   }
 }

package/src/catalogs/en.json

@@ -124,71 +124,180 @@
     "noMore": "That's everything."
   },
   "admin": {
-    "nav": {
-      "dashboard": "Dashboard",
-      "entities": "Data",
-      "actions": "Actions",
-      "jobs": "Jobs",
-      "tasks": "Schedules",
-      "queries": "Queries",
-      "policies": "Policies",
-      "users": "Users",
-      "settings": "Settings",
-      "logs": "Logs",
-      "traces": "Traces",
-      "migrations": "Migrations"
+    "a11y": {
+      "skip-to-content": "Skip to content"
+    },
+    "actions": {
+      "label": "Actions",
+      "confirm": {
+        "title": "Confirm before this runs",
+        "body": "Type {token} to confirm. Nothing happens until it matches.",
+        "label": "Confirmation",
+        "submit": "Run it"
+      }
+    },
+    "ai": {
+      "disabled": "AI panes are switched off for this admin.",
+      "no-runner": "No AI runner is wired, so this pane has nothing to ask.",
+      "anomaly": {
+        "title": "Anomalies",
+        "description": "Rows that look unlike the rest of the table."
+      },
+      "nl-query": {
+        "title": "Ask the data",
+        "description": "A question in plain language, answered as a read-only query."
+      },
+      "forecast": {
+        "title": "Forecast",
+        "description": "Where this series is heading, from the rows already stored."
+      }
+    },
+    "audit": {
+      "title": "Audit trail",
+      "empty": "Nothing has been done to this row yet.",
+      "outcome": {
+        "allowed": "Allowed",
+        "denied": "Denied",
+        "failed": "Failed"
+      }
+    },
+    "brand": {
+      "name": "Admin"
     },
     "dashboard": {
-      "title": "Dashboard",
-      "health": "Health",
-      "throughput": "Requests per minute",
-      "errorRate": "Error rate",
-      "latency": "p95 latency",
-      "queueDepth": "Queue depth",
-      "activeUsers": "Active users",
-      "since": "since {when}"
+      "title": "Dashboard"
+    },
+    "denied": {
+      "body": "This account is missing {permission} ({reason})."
+    },
+    "detail": {
+      "edit": "Edit",
+      "loading": "Loading…",
+      "not-found": {
+        "cause": "No {entity} with that id.",
+        "fix": "Go back to the list and open a row that still exists."
+      }
+    },
+    "error": {
+      "action-failed": "The action threw before it finished.",
+      "confirmation-required": "This is destructive: echo the confirmation token first.",
+      "invalid-input": "Some fields did not pass the entity's own schema."
+    },
+    "form": {
+      "cancel": "Cancel",
+      "create": "New {entity}",
+      "edit": "Edit {entity}",
+      "issues": "Check the highlighted fields",
+      "save": "Save",
+      "saving": "Saving…"
+    },
+    "group": {
+      "data": "Data"
     },
     "jobs": {
-      "title": "Jobs",
-      "queued": "Queued",
-      "running": "Running",
-      "succeeded": "Succeeded",
-      "failed": "Failed",
-      "retrying": "Retrying",
-      "cancelled": "Cancelled",
-      "attempt": "Attempt {attempt} of {attempts}",
-      "nextRun": "Next run {when}",
-      "retryNow": "Retry now",
-      "cancel": "Cancel job",
-      "step": "Step {name}",
-      "pending": "{count} job waiting",
-      "pending_plural": "{count} jobs waiting"
-    },
-    "tasks": {
-      "title": "Schedules",
-      "cron": "Cron",
-      "timezone": "Timezone",
-      "lastRun": "Last run",
-      "nextRun": "Next run",
-      "runNow": "Run now",
-      "pause": "Pause",
-      "resume": "Resume"
-    },
-    "entities": {
-      "title": "Data",
-      "rows": "{count} row",
-      "rows_plural": "{count} rows",
-      "newRecord": "New {entity}",
-      "deleteRecord": "Delete this {entity}?",
-      "noResults": "No {entity} matched that filter."
-    },
-    "table": {
-      "sortAscending": "Sort ascending",
-      "sortDescending": "Sort descending",
-      "columns": "Columns",
-      "selected": "{count} selected",
-      "selectAll": "Select all",
-      "clearSelection": "Clear selection"
+      "title": "Jobs"
+    },
+    "list": {
+      "empty": "Nothing here yet.",
+      "loading": "Loading…",
+      "next": "Next",
+      "open": "Open",
+      "pagination": "Pagination",
+      "previous": "Previous"
+    },
+    "nav": {
+      "label": "Sections"
+    },
+    "operation": {
+      "list": "listed",
+      "detail": "read",
+      "search": "searched",
+      "create": "created",
+      "update": "updated",
+      "delete": "deleted",
+      "page": "opened a page"
+    },
+    "permission": {
+      "read": "Read every admin screen",
+      "write": "Create and update rows",
+      "destroy": "Delete rows",
+      "impersonate": "Act as another account"
+    },
+    "policy": {
+      "all-granted": "every required permission is granted",
+      "evaluated": "the policy decided this",
+      "granted": "the grant list contains this permission",
+      "missing": "no policy is registered for this permission",
+      "not-granted": "the grant list does not contain this permission"
+    },
+    "search": {
+      "title": "Search",
+      "label": "Search",
+      "placeholder": "Search every entity",
+      "skipped": {
+        "forbidden": "this account may not search that entity",
+        "no-text-fields": "that entity has no text field to search",
+        "no-repo": "that entity has no repo bound"
+      }
+    },
+    "value": {
+      "empty": "—",
+      "true": "Yes",
+      "false": "No"
+    }
+  },
+  "dev": {
+    "panel": {
+      "routes": {
+        "title": "Routes",
+        "question": "which handler serves this?"
+      },
+      "timeline": {
+        "title": "Timeline",
+        "question": "where did the time go in this request?"
+      },
+      "live": {
+        "title": "Live",
+        "question": "what does each subscriber receive, and why?"
+      },
+      "jobs": {
+        "title": "Jobs",
+        "question": "is the queue moving, and which step failed?"
+      },
+      "db": {
+        "title": "DB",
+        "question": "what is in the table, and does the schema match the migrations?"
+      },
+      "mail": {
+        "title": "Mail",
+        "question": "what did that email look like, in that locale?"
+      },
+      "cache": {
+        "title": "Cache",
+        "question": "what invalidated what — and why is this still stale?"
+      },
+      "policy": {
+        "title": "Policy",
+        "question": "can this actor do that, and why?"
+      },
+      "manifest": {
+        "title": "Manifest",
+        "question": "is the committed x.manifest.json current?"
+      },
+      "services": {
+        "title": "Services",
+        "question": "which services is this process talking to, and did anything fail to load?"
+      },
+      "boundaries": {
+        "title": "Boundaries",
+        "question": "does any file import across a boundary the build will reject?"
+      }
+    },
+    "live": {
+      "no-sync-node": "no sync node is attached — subscriber facts need a running x dev process"
+    },
+    "cache": {
+      "no-invalidations-yet": "no invalidation has been logged yet — the graph above is still real"
     }
   },
   "time": {
@@ -208,5 +317,49 @@
     "relative": {
       "now": "just now"
     }
+  },
+  "ui": {
+    "breadcrumb": "Breadcrumb",
+    "cancel": "Cancel",
+    "close": "Close",
+    "confirm": "Confirm",
+    "dismiss": "Dismiss",
+    "empty": "Nothing here yet.",
+    "error": {
+      "code": "Error code",
+      "cause": "What went wrong",
+      "fix": "How to fix it",
+      "title": "Something went wrong"
+    },
+    "language": "Language",
+    "load": {
+      "more": "Load more",
+      "end": "That's everything."
+    },
+    "loading": "Loading…",
+    "menu": "Menu",
+    "more": "More",
+    "navigation": "Navigation",
+    "next": "Next",
+    "optional": "Optional",
+    "page": "Page",
+    "previous": "Previous",
+    "required": "Required",
+    "results": {
+      "empty": "No matches"
+    },
+    "retry": "Try again",
+    "skip": "Skip to content",
+    "sort": {
+      "ascending": "Sort ascending",
+      "descending": "Sort descending"
+    },
+    "suggestions": "{count} suggestions",
+    "theme": {
+      "light": "Light",
+      "dark": "Dark",
+      "system": "System",
+      "label": "Theme"
+    }
   }
 }

package/src/context.ts

@@ -3,7 +3,7 @@
  * No call site passes a locale by hand — `t()` here is the ambient translator.
  */
 
-import { type Ctx, useContext } from '@ultimat3/core';
+import { tryUseContext } from '@ultimat3/core';
 import { type Catalog, mergeCatalogs } from './catalog';
 import {
   DEFAULT_LOCALE,
@@ -19,9 +19,6 @@ import { createTranslator, type TranslateVars, type Translator } from './transla
 /** The cookie an explicit language switcher writes. */
 export const LOCALE_COOKIE = 'x_locale';
 
-/** Field name on the ALS context. Core owns `Ctx`; it stays a plain string there. */
-const CTX_LOCALE = 'locale';
-
 export interface LocaleSources {
   /** Raw `Accept-Language` header value. */
   header?: string | null;
@@ -49,7 +46,13 @@ export interface LocaleConfig {
   order: readonly LocaleSourceName[];
 }
 
-const DEFAULT_ORDER: readonly LocaleSourceName[] = ['header', 'cookie', 'user', 'query'];
+/**
+ * Explicit before inferred, always. `Accept-Language` is what the browser was installed as; the
+ * query, the cookie and the user row are what a person *chose*. Ranking the header first meant a
+ * language switcher wrote a cookie that never won again — and `@ultimat3/http`'s negotiator, which
+ * takes the explicit value ahead of the header, disagreed with this one about the same request.
+ */
+const DEFAULT_ORDER: readonly LocaleSourceName[] = ['query', 'cookie', 'user', 'header'];
 
 let config: LocaleConfig = {
   supported: SUPPORTED_LOCALES,
@@ -68,7 +71,7 @@ export function localeConfig(): LocaleConfig {
 }
 
 /**
- * Header → cookie → user record → query → default, per `config.order`.
+ * Query → cookie → user record → header → default, per `config.order`.
  * An unsupported tag is skipped rather than thrown: a stale cookie must not 500 a page.
  */
 export function resolveLocale(
@@ -95,25 +98,29 @@ export function localeCookieOf(cookieHeader?: string | null): string | undefined
     const index = pair.indexOf('=');
     if (index === -1) continue;
     if (pair.slice(0, index).trim() !== LOCALE_COOKIE) continue;
-    return decodeURIComponent(pair.slice(index + 1).trim());
+    const raw = pair.slice(index + 1).trim();
+    try {
+      return decodeURIComponent(raw);
+    } catch {
+      // A cookie is client-authored: `x_locale=%` is a `URIError` out of a per-request path, and
+      // a 500 for a malformed locale is worse than the raw value, which `resolveLocale` then
+      // fails to normalise and skips. Same guard as `@ultimat3/auth`'s `decodeCookieValue`.
+      return raw;
+    }
   }
   return undefined;
 }
 
-/** The HTTP layer calls this once per request, before any render. */
-export function attachLocale(ctx: Ctx, locale: Locale): Locale {
-  writeContextField(ctx, CTX_LOCALE, locale);
-  return locale;
-}
-
-export function localeOf(ctx: Ctx): Locale {
-  return readField(ctx, CTX_LOCALE) ?? config.fallback;
-}
-
-/** Ambient locale for the in-flight request; the configured fallback outside one. */
+/**
+ * Ambient locale for the in-flight request; the configured fallback outside one.
+ *
+ * The store is **`Ctx.locale`**, core's own declared field, so `createContext({ locale })` and
+ * `withChildContext({ locale })` are the only writers and this package publishes no second one.
+ * `@ultimat3/time`'s `currentTimeZone()` is the same shape over `Ctx.tz`, deliberately.
+ */
 export function currentLocale(): Locale {
-  const ctx = tryContext();
-  return (ctx === undefined ? undefined : readField(ctx, CTX_LOCALE)) ?? config.fallback;
+  const locale = tryUseContext()?.locale;
+  return locale === undefined || locale === '' ? config.fallback : locale;
 }
 
 export function currentDirection(): Direction {
@@ -171,25 +178,3 @@ export function resetCatalogs(): void {
   registry.clear();
   translators.clear();
 }
-
-function tryContext(): Ctx | undefined {
-  try {
-    return useContext();
-  } catch {
-    // Outside a request scope (boot, a CLI command, a worker tick) — no ambient locale.
-    return undefined;
-  }
-}
-
-/**
- * `Ctx` is owned by core (tier 0) and cannot reference i18n's `Locale`, so the field is
- * read structurally. One place, one cast, validated on the way out.
- */
-function readField(ctx: Ctx, field: string): string | undefined {
-  const value = (ctx as unknown as Record<string, unknown>)[field];
-  return typeof value === 'string' && value !== '' ? value : undefined;
-}
-
-function writeContextField(ctx: Ctx, field: string, value: string): void {
-  (ctx as unknown as Record<string, unknown>)[field] = value;
-}

package/src/framework.ts

@@ -8,7 +8,13 @@ import en from './catalogs/en.json';
 import { registerCatalog } from './context';
 import { DEFAULT_LOCALE, type Locale } from './locales';
 
-/** `errors.*`, `auth.*`, `pagination.*`, `admin.*`, `validation.*`, `common.*`, `time.*`. */
+/**
+ * `errors.*`, `auth.*`, `pagination.*`, `admin.*`, `validation.*`, `common.*`, `time.*`, `ui.*`.
+ *
+ * `ui.*` is `@ultimat3/ui`'s `UI_KEYS` — the strings the design system needs and cannot receive as
+ * a prop. They live here rather than in that package because a catalog is one flat file per locale
+ * and a second one would be a second place a translator has to find.
+ */
 export const FRAMEWORK_CATALOG: Catalog = loadCatalog(en);
 
 export const FRAMEWORK_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;

package/src/index.ts

@@ -12,7 +12,6 @@ export {
   parseNestedCatalog,
 } from './catalog';
 export {
-  attachLocale,
   catalogFor,
   configureLocales,
   currentDirection,
@@ -24,7 +23,6 @@ export {
   type LocaleSources,
   localeConfig,
   localeCookieOf,
-  localeOf,
   registerCatalog,
   registeredLocales,
   resetCatalogs,

package/src/interpolate.ts

@@ -22,14 +22,22 @@ const PLACEHOLDER = /\{\{|\}\}|\{([^{}\s]+)\}/g;
  * Replace `{name}` with `vars.name`. `{{` and `}}` escape a literal brace.
  * An unknown variable renders loudly as `⟦name⟧` for the same reason a missing key
  * does: a silently blank slot ships to production, a bracketed one does not.
+ *
+ * Only an OWN property of `vars` is a variable. A plain object inherits `constructor`,
+ * `toString` and the rest, so `{constructor}` would have rendered a function's source into a
+ * page — the same prototype walk `catalog.ts` avoids by nesting into null-prototype nodes.
+ *
+ * The fast path tests both braces because `}}` un-escapes without a `{` in sight: skipping on
+ * `{` alone left `'a}}b'` unchanged while `'{{a}}b'` collapsed, which is one escape with two
+ * meanings.
  */
 export function interpolate(template: string, vars?: InterpolationVars): string {
-  if (!template.includes('{')) return template;
+  if (!template.includes('{') && !template.includes('}')) return template;
   return template.replace(PLACEHOLDER, (match, name: string | undefined) => {
     if (match === '{{') return '{';
     if (match === '}}') return '}';
     if (name === undefined) return match;
-    const value = vars?.[name];
+    const value = vars !== undefined && Object.hasOwn(vars, name) ? vars[name] : undefined;
     if (value === undefined) return `⟦${name}⟧`;
     return String(value);
   });
@@ -57,15 +65,27 @@ export function pluralCategory(count: number, locale: string): Intl.LDMLPluralRu
 /**
  * Candidate keys for a plural lookup, most specific first.
  *
- * `items` + count 3 in `pl` → `items_many`, `items_plural`, `items_other`, `items`.
- * `items` + count 1 in `pl` → `items_one`, `items`.
+ * `items` + count 5 in `pl` → `items_many`, `items_plural`, `items_other`, `items`, `items_one`.
+ * `items` + count 1 in `pl` → `items_one`, `items`, `items_plural`, `items_other`.
  * `_plural` is the two-form authoring shortcut from the house style; the `_<category>`
  * suffixes are what a 3+ form locale needs.
+ *
+ * Both chains END on the same four candidates — `key`, `_one`, `_plural`, `_other` — because those
+ * are exactly what `Translator.has()` answers true for, and `has()` is what a caller GUARDS a
+ * render with (`packages/mail/src/render.ts:48`). A chain narrower than `has()` puts ⟦key⟧ into
+ * copy a guard had just promised was renderable. Only the ORDER differs by category, and that is
+ * the point: for `one` the bare key is the singular half of the two-form shortcut, so it outranks
+ * the plural forms; everywhere else it is the last-resort singular.
  */
 export function pluralKeyCandidates(key: string, count: number, locale: string): string[] {
   const category = pluralCategory(count, locale);
-  if (category === 'one') return [`${key}_one`, key];
-  return [`${key}_${category}`, `${key}_plural`, `${key}_other`, key];
+  const chain =
+    category === 'one'
+      ? [`${key}_one`, key, `${key}_plural`, `${key}_other`]
+      : [`${key}_${category}`, `${key}_plural`, `${key}_other`, key, `${key}_one`];
+  // `other` names itself twice without this — the duplicate is harmless and was the tell that the
+  // list had never been exercised.
+  return [...new Set(chain)];
 }
 
 /** First candidate that exists, per the caller's `has` predicate; falls back to `key`. */