@ultimat3/i18n 29.3.2 → 30.0.0

package/CLAUDE.md

@@ -18,6 +18,7 @@ Imported by every package that renders a string.
 | `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. |
+| `recording-translator.ts` | a translator that records what it could not answer: `TranslationMiss` |
 
 ## Rules
 
@@ -123,6 +124,9 @@ Imported by every package that renders a string.
 - 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`.
+- `extract.ts` names no framework API. A new key-bearing shape goes in `cli/src/i18n-app-key-shapes.ts` as a callee or a `properties` entry, never in `DEFAULT_CALLEES`: the framework's own scan (`scripts/lib/i18n-scan.ts`) shares this function and its `mail.*` keys live outside `catalogs/en.json`.
+- **`selectMessageKey` (`interpolate.ts`) is the one key selection.** `t()` and `recordingTranslator` both call it; a new selecting var goes there, or a mail refuses a key `t()` can answer. Every key `has()` answers true for renders: a missing family var still reaches `_select_other`/`_ordinal_other`.
+- `auditCatalogs`'s `required` is `used` plus the `reference` locale's stems. `used` stays what source names; `unused` still compares against `used` alone.
 
 ## Commands
 

package/README.md

@@ -5,6 +5,8 @@ Every string goes through `t()`. A key with no translation renders `⟦key⟧`
 never the English fallback, never silence. Numbers, dates and money are **not** i18n
 strings: format those with `Intl` via [@ultimat3/money](../money) and [@ultimat3/time](../time).
 
+`bun add @ultimat3/i18n` · guide: [I18n](https://github.com/developerz-ai/ultimate/wiki/I18n)
+
 | Concern | Owner | Rule |
 |---|---|---|
 | Registration | `define-catalogs.ts` | `defineCatalogs()` — one call, at boot, per app |
@@ -126,13 +128,20 @@ The one reader the CLI (`loadApp`'s `locales`, the pwa manifest and service work
 
 ## Enforcement
 
-`extractKeys()` scans source for `t('...')` calls; `auditCatalogs()` reports keys used,
-keys missing per locale, and keys defined but never used; `assertCatalogsComplete()` is
+`recordingTranslator(t)` wraps a translator and records each `TranslationMiss` (`{ key, slot? }`) for
+a surface that refuses rather than shows `⟦key⟧`; `selectMessageKey()` is the one key selection it
+and `t()` share.
+
+`extractKeys()` scans source for `t('...')` calls, plus any other `callees` and key-bearing
+`properties` (`{ name, whenFileContains? }`: a literal value is a usage, anything else `dynamic`)
+the caller declares; this package names no API but its own. `auditCatalogs()` reports keys used,
+keys missing per locale (`reference` makes each key that locale defines owed by the rest, by
+plural stem, in `required`), and keys defined but never used; `assertCatalogsComplete()` is
 the `x verify` gate.
 
 ```
 X_CATALOG_MISSING_KEYS: catalog is incomplete
-  cause: packages/i18n/catalogs/es.json is missing 2 key(s) used in source: admin.nav.jobs, common.save
+  cause: packages/i18n/catalogs/es.json is missing 2 key(s) source names or the reference locale defines: admin.nav.jobs, common.save
   fix:   x i18n sync es
 ```
 

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "Dependency-free translator, catalog flattening, locale negotiation and loud missing-key rendering",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "i18n",
+    "l10n",
+    "translation",
+    "intl"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/I18n",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -38,6 +48,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.2"
+    "@ultimat3/core": "30.0.0"
   }
 }

package/src/catalogs/en.json

@@ -173,7 +173,16 @@
     },
     "audit": {
       "title": "Audit trail",
-      "empty": "Nothing has been done to this row yet.",
+      "empty": "No entry in the trail matches.",
+      "empty-row": "Nothing has been done to this row yet.",
+      "filter": {
+        "entity": "Entity",
+        "actor": "Actor",
+        "outcome": "Outcome",
+        "since": "From",
+        "until": "Before",
+        "changes": "Changes and refusals only"
+      },
       "outcome": {
         "allowed": "Allowed",
         "denied": "Denied",
@@ -490,6 +499,38 @@
           "step": "Step"
         }
       }
+    },
+    "errors": {
+      "title": "Errors",
+      "detail": {
+        "title": "Error group"
+      },
+      "status": {
+        "open": "Open",
+        "resolved": "Resolved",
+        "ignored": "Ignored"
+      },
+      "field": {
+        "code": "Code",
+        "source": "Source",
+        "operation": "Operation",
+        "status": "Status",
+        "count": "Occurrences",
+        "first-seen": "First seen",
+        "last-seen": "Last seen",
+        "release": "Release",
+        "environment": "Environment",
+        "request": "Request",
+        "trace": "Trace"
+      },
+      "filter": {
+        "status": "Filter errors by status"
+      },
+      "empty": "No error groups match this filter.",
+      "count": "{count} occurrence",
+      "count_plural": "{count} occurrences",
+      "missing": "This error group no longer exists.",
+      "back": "Back to errors"
     }
   },
   "dev": {
@@ -599,10 +640,18 @@
   "ui": {
     "breadcrumb": "Breadcrumb",
     "cancel": "Cancel",
+    "chart": {
+      "none": "No data"
+    },
     "close": "Close",
     "confirm": "Confirm",
     "copied": "Copied",
     "copy": "Copy",
+    "date": {
+      "open": "Choose a date",
+      "previousMonth": "Previous month",
+      "nextMonth": "Next month"
+    },
     "dismiss": "Dismiss",
     "empty": "Nothing here yet.",
     "error": {
@@ -611,7 +660,17 @@
       "fix": "How to fix it",
       "title": "Something went wrong"
     },
+    "first": "First",
     "language": "Language",
+    "list": {
+      "toEnd": "Back to the end"
+    },
+    "live": {
+      "live": "Live",
+      "reconnecting": "Reconnecting",
+      "paused": "Paused",
+      "offline": "Offline"
+    },
     "load": {
       "more": "Load more",
       "end": "That's everything."
@@ -628,18 +687,73 @@
     "results": {
       "empty": "No matches"
     },
+    "range": {
+      "open": "Choose dates",
+      "from": "From",
+      "to": "To",
+      "apply": "Apply",
+      "custom": "Custom range",
+      "invalid": "That range is not valid, so the default is shown."
+    },
+    "refresh": {
+      "pull": "Pull to refresh",
+      "release": "Release to refresh",
+      "busy": "Refreshing…"
+    },
     "retry": "Try again",
+    "select": {
+      "none": "Nothing chosen",
+      "more": "Showing {shown} of {total} — type to narrow",
+      "remove": "Remove {label}",
+      "clear": "Clear"
+    },
+    "shortcuts": "Keyboard shortcuts",
     "skip": "Skip to content",
     "sort": {
       "ascending": "Sort ascending",
-      "descending": "Sort descending"
-    },
+      "descending": "Sort descending",
+      "handle": "Move",
+      "target": "Move to",
+      "lift": "Lifted, position {position} of {total} in {group}. Arrow keys move it, Space drops it, Escape puts it back.",
+      "moved": "Position {position} of {total} in {group}.",
+      "dropped": "Dropped at position {position} of {total} in {group}.",
+      "cancelled": "Not moved: back at position {position} of {total} in {group}.",
+      "up": "Move up",
+      "down": "Move down"
+    },
+    "step": "Step {current} of {total}: {label}",
     "suggestions": "{count} suggestions",
     "theme": {
       "light": "Light",
       "dark": "Dark",
       "system": "System",
       "label": "Theme"
+    },
+    "tree": {
+      "loading": "Loading children…"
+    },
+    "pane": {
+      "resize": "Resize panes"
+    },
+    "code": {
+      "region": "Code",
+      "wrap": "Wrap lines",
+      "terminal": "Terminal output"
+    },
+    "diff": {
+      "region": "Changes",
+      "added": "Added",
+      "removed": "Removed",
+      "next": "Next change",
+      "folded": "{count} more lines not shown"
+    },
+    "log": {
+      "region": "Log",
+      "filter": "Filter lines",
+      "level": "Level",
+      "all": "Every level",
+      "follow": "Follow the end",
+      "capped": "Showing the last {count} lines"
     }
   }
 }

package/src/errors.ts

@@ -10,6 +10,7 @@ export const I18N_ERROR_CODES = [
   'X_CATALOG_MISSING_KEYS',
   'X_CATALOG_INVALID',
   'X_CATALOG_UNREGISTERED',
+  'X_I18N_FAMILY_INCOMPLETE',
 ] as const;
 
 export type I18nErrorCode = (typeof I18N_ERROR_CODES)[number];
@@ -19,6 +20,7 @@ export const I18N_ERROR_TITLES: Readonly<Record<I18nErrorCode, string>> = {
   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',
+  X_I18N_FAMILY_INCOMPLETE: 'a select or ordinal family has no _other',
 };
 
 // Titles must be registered for format() to render the contract's first line. Every code above is
@@ -55,11 +57,20 @@ export function catalogMissingKeys(locale: string, keys: readonly string[]): I18
   const suffix = keys.length > shown.length ? `, +${keys.length - shown.length} more` : '';
   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}`,
+    cause: `packages/i18n/catalogs/${locale}.json is missing ${keys.length} key(s) source names or the reference locale defines: ${shown.join(', ')}${suffix}`,
     fix: `x i18n sync ${locale}   # writes each key above as ⟦key⟧ — replace every one with the real string`,
   });
 }
 
+/** A select or ordinal family with no `_other`: a value it does not name renders `⟦key⟧`. */
+export function familyIncomplete(locale: string, owed: readonly string[]): I18nError {
+  return new I18nError({
+    code: 'X_I18N_FAMILY_INCOMPLETE',
+    cause: `packages/i18n/catalogs/${locale}.json defines a select or ordinal family with no _other, so a value it does not name renders the loud miss: ${shownKeys(owed)}`,
+    fix: `x i18n check --json   # then add each key named here (${owed[0] ?? '<key>_select_other'}) to packages/i18n/catalogs/${locale}.json`,
+  });
+}
+
 /**
  * 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.

package/src/extract.ts

@@ -6,7 +6,7 @@
 
 import { stripComments } from '@ultimat3/core';
 import { type Catalog, catalogKeys } from './catalog';
-import { catalogMissingKeys } from './errors';
+import { catalogMissingKeys, familyIncomplete } from './errors';
 import { PLURAL_CATEGORIES } from './interpolate';
 import type { Locale } from './locales';
 
@@ -34,24 +34,42 @@ export interface LocaleAudit {
   locale: Locale;
   missing: string[];
   unused: string[];
+  /** Select and ordinal families with no `_other`: `<family>_other` is what each one owes. */
+  incomplete: string[];
 }
 
 export interface ExtractReport {
   /** Distinct static keys, sorted. */
   used: string[];
+  /** What every locale owes: `used` plus each stem the reference locale defines, sorted. */
+  required: string[];
   usages: KeyUsage[];
   dynamic: DynamicUsage[];
   locales: LocaleAudit[];
   ok: boolean;
 }
 
+/** A property whose value is a catalog key, for an API that takes keys rather than strings. */
+export interface KeyProperty {
+  name: string;
+  /** Only in a file holding this text: a bare `subject:` means nothing on its own. */
+  whenFileContains?: string;
+}
+
 export interface ExtractOptions {
   /** Call names treated as translator calls. */
   callees?: readonly string[];
+  /** Properties whose literal value is a usage and whose any other value is `dynamic`. */
+  properties?: readonly KeyProperty[];
 }
 
 const DEFAULT_CALLEES: readonly string[] = ['t', '$t', 'translate'];
-const STRING_LITERAL = /^(['"`])((?:[^\\]|\\.)*?)\1$/s;
+// The closing quote may not recur inside: `'a' + 'b'` is two literals, not a key spelled `a' + 'b`.
+const STRING_LITERAL = /^(['"`])((?:(?!\1)[^\\]|\\.)*)\1$/s;
+// A value runs to the first comma, closer or line break outside a string. Strings are matched whole
+// so a comma in one does not end it. The trailing `;` is captured because it marks a type member
+// (`titleKey: string;`): an object literal never ends a property with one.
+const PROPERTY_VALUE = String.raw`((?:'(?:[^'\\\n]|\\.)*'|"(?:[^"\\\n]|\\.)*"|\`(?:[^\`\\]|\\.)*\`|[^,;})\n'"\`])*)(;?)`;
 
 /**
  * Scan one source file. Deliberately a lexer-free scan: a translator call is a
@@ -72,26 +90,43 @@ export function extractKeys(
 
   const usages: KeyUsage[] = [];
   const dynamic: DynamicUsage[] = [];
-
-  // Over the COMMENT-STRIPPED text, never the raw file: a `// … t('…', { … })` in a comment matched
-  // the shape above and produced a phantom key that `x i18n sync` would have written into every
-  // catalog as `"…": "⟦…⟧"` (measured 2026-09-05). The mask keeps every newline and every string
-  // literal in place, so an index into it is an index into `source` and the positions below hold.
-  for (const match of stripComments(source).matchAll(pattern)) {
-    const argument = (match[1] ?? '').trim();
-    const index = match.index ?? 0;
+  const record = (rawArgument: string | undefined, index: number): void => {
+    const argument = (rawArgument ?? '').trim();
     const position = positionOf(source, index);
-    if (argument === '') continue;
+    if (argument === '') return;
     const literal = STRING_LITERAL.exec(argument);
     const key = literal?.[2];
     if (key === undefined || key.includes('${')) {
       dynamic.push({ expression: argument, file, ...position });
-      continue;
+      return;
     }
     usages.push({ key, file, ...position });
+  };
+
+  // Over the COMMENT-STRIPPED text, never the raw file: a `// … t('…', { … })` in a comment matched
+  // the shape above and produced a phantom key that `x i18n sync` would have written into every
+  // catalog as `"…": "⟦…⟧"` (measured 2026-09-05). The mask keeps every newline and every string
+  // literal in place, so an index into it is an index into `source` and the positions below hold.
+  const stripped = stripComments(source);
+  const properties = options.properties ?? [];
+  for (const match of stripped.matchAll(pattern)) record(match[1], match.index ?? 0);
+
+  // Properties are read in CODE only: `stripComments` keeps strings, and a fix line or a docs
+  // example quoting `{ titleKey: 'x' }` is text. The value is still read off `stripped`.
+  const code = properties.length === 0 ? stripped : blankStrings(stripped);
+  for (const property of properties) {
+    const marker = property.whenFileContains;
+    if (marker !== undefined && !code.includes(marker)) continue;
+    const name = escapeRegExp(property.name);
+    // Not after an identifier char, a `.` or a quote: `subtitleKey`, `a.titleKey`, `'x.titleKey'`.
+    const shape = new RegExp(String.raw`(?<![\w$.'"-])${name}\s*:\s*${PROPERTY_VALUE}`, 'g');
+    for (const match of stripped.matchAll(shape)) {
+      const index = match.index ?? 0;
+      if (match[2] !== ';' && code[index] === stripped[index]) record(match[1], index);
+    }
   }
 
-  return { usages, dynamic };
+  return { usages: usages.sort(bySourceOrder), dynamic: dynamic.sort(bySourceOrder) };
 }
 
 export interface AuditInput {
@@ -100,35 +135,53 @@ export interface AuditInput {
   catalogs: Readonly<Record<Locale, Catalog>>;
   /** Keys resolved at runtime (e.g. `time.cron.*`) — never reported unused. */
   ignoreUnused?: readonly string[];
+  /** Every locale also owes each key this one defines, compared by plural stem. */
+  reference?: Locale;
 }
 
 /**
  * A used key counts as present when the locale defines it *or* any of its plural
  * variants: `pl` legitimately defines `items_one`/`items_few`/`items_many` and no bare
- * `items`, and that must not read as a missing key.
+ * `items`, and that must not read as a missing key. The same comparison serves `reference`, so
+ * `ja`'s lone `items_other` answers `en`'s `items_one`/`items_other`.
  */
 export function auditCatalogs(input: AuditInput): ExtractReport {
   const used = [...new Set(input.extraction.usages.map((usage) => usage.key))].sort();
   const ignore = input.ignoreUnused ?? [];
+  // By family stem too: a locale with no grammatical gender owes `invite`, and its lone
+  // `invite_select_other` answers it — never every value the reference names.
+  const referenced = catalogKeys(input.catalogs[input.reference ?? ''] ?? {}).map((key) =>
+    familyStemOf(stemOf(key)),
+  );
+  const required = [...new Set([...used, ...referenced])].sort();
 
   const locales: LocaleAudit[] = Object.keys(input.catalogs)
     .sort()
     .map((locale) => {
       const catalog = input.catalogs[locale] ?? {};
-      const missing = used.filter((key) => !definesKey(catalog, key));
+      const missing = required.filter((key) => !definesKey(catalog, key));
       const usedWithVariants = new Set(used.flatMap(variantsOf));
+      const usedSet = new Set(used);
+      // A family member is used when its stem is: `t('invite', { select })` reads every one.
       const unused = catalogKeys(catalog).filter(
-        (key) => !usedWithVariants.has(key) && !isIgnored(key, ignore),
+        (key) =>
+          !usedWithVariants.has(key) && !usedSet.has(familyStemOf(key)) && !isIgnored(key, ignore),
       );
-      return { locale, missing, unused };
+      return {
+        locale,
+        missing,
+        unused,
+        incomplete: incompleteFamilies(catalogKeys(catalog), usedSet),
+      };
     });
 
   return {
     used,
+    required,
     usages: input.extraction.usages,
     dynamic: input.extraction.dynamic,
     locales,
-    ok: locales.every((audit) => audit.missing.length === 0),
+    ok: locales.every((audit) => audit.missing.length === 0 && audit.incomplete.length === 0),
   };
 }
 
@@ -136,6 +189,7 @@ export function auditCatalogs(input: AuditInput): ExtractReport {
 export function assertCatalogsComplete(report: ExtractReport): void {
   for (const audit of report.locales) {
     if (audit.missing.length > 0) throw catalogMissingKeys(audit.locale, audit.missing);
+    if (audit.incomplete.length > 0) throw familyIncomplete(audit.locale, audit.incomplete);
   }
 }
 
@@ -159,19 +213,114 @@ export async function extractFromFiles(
 }
 
 function definesKey(catalog: Catalog, key: string): boolean {
-  return variantsOf(key).some((candidate) => Object.hasOwn(catalog, candidate));
+  return (
+    variantsOf(key).some((candidate) => Object.hasOwn(catalog, candidate)) ||
+    catalogKeys(catalog).some((defined) => familyStemOf(defined) === key)
+  );
+}
+
+const FAMILY = /_(select|ordinal)_/;
+
+/** `invite_select_female_one` → `invite`; a key in no family is its own. */
+function familyStemOf(key: string): string {
+  const match = FAMILY.exec(key);
+  return match === null || match.index === 0 ? key : key.slice(0, match.index);
+}
+
+/**
+ * Every family prefix (`invite_select`, `place_ordinal`, `invite_select_female_ordinal`) whose
+ * `_other` — bare or plural-suffixed — the catalog does not define: a value the family does not
+ * name would render the loud miss. Answered as the key owed, `<prefix>_other`. A key source names
+ * itself (`t('theme_select_label')`) is an ordinary key that happens to spell `_select_`, never a
+ * family member: it owes no `theme_select_other`.
+ */
+function incompleteFamilies(keys: readonly string[], named: ReadonlySet<string>): string[] {
+  const defined = new Set(keys);
+  const owed = new Set<string>();
+  for (const key of keys) {
+    if (named.has(stemOf(key))) continue;
+    for (const match of key.matchAll(/_(select|ordinal)_/g)) {
+      if (match.index === 0) continue;
+      const prefix = key.slice(0, match.index + match[0].length - 1);
+      const other = `${prefix}_other`;
+      const present =
+        variantsOf(other).some((candidate) => defined.has(candidate)) ||
+        keys.some((candidate) => candidate.startsWith(`${other}_`));
+      if (!present) owed.add(other);
+    }
+  }
+  return [...owed].sort();
 }
 
 function variantsOf(key: string): string[] {
   return [key, `${key}_plural`, ...PLURAL_CATEGORIES.map((category) => `${key}_${category}`)];
 }
 
+/** `items_few` → `items`. Anything else is its own stem: `sort_order` is no plural. */
+function stemOf(key: string): string {
+  const cut = key.lastIndexOf('_');
+  if (cut <= 0) return key;
+  const suffix = key.slice(cut + 1);
+  const plural = suffix === 'plural' || PLURAL_CATEGORIES.some((category) => category === suffix);
+  return plural ? key.slice(0, cut) : key;
+}
+
 function isIgnored(key: string, patterns: readonly string[]): boolean {
   return patterns.some((pattern) =>
     pattern.endsWith('*') ? key.startsWith(pattern.slice(0, -1)) : key === pattern,
   );
 }
 
+const BLANK = '\u0000';
+
+/**
+ * `text` with every string literal's contents replaced by `BLANK`, same length, so an index into it is
+ * an index into `text`. A template's `${…}` is code and stays: a key can be written there.
+ */
+function blankStrings(text: string): string {
+  let out = '';
+  // One entry per open template: the brace depth of its `${…}`, or -1 while in its text.
+  const templates: number[] = [];
+  let quote: string | undefined;
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i] ?? '';
+    const top = templates.length - 1;
+    const inTemplateText = quote === undefined && templates[top] === -1;
+    if (quote !== undefined || inTemplateText) {
+      if (char === '\\') {
+        out += BLANK + (text[i + 1] === undefined ? '' : BLANK);
+        i += 1;
+      } else if (quote !== undefined && (char === quote || char === '\n')) {
+        quote = undefined;
+        out += char;
+      } else if (inTemplateText && char === '`') {
+        templates.pop();
+        out += char;
+      } else if (inTemplateText && char === '$' && text[i + 1] === '{') {
+        templates[top] = 0;
+        out += '${';
+        i += 1;
+      } else {
+        out += char === '\n' ? char : BLANK;
+      }
+      continue;
+    }
+    if (char === "'" || char === '"') quote = char;
+    else if (char === '`') templates.push(-1);
+    else if (top >= 0 && char === '{') templates[top] = (templates[top] ?? 0) + 1;
+    else if (top >= 0 && char === '}') {
+      const depth = templates[top] ?? 0;
+      templates[top] = depth === 0 ? -1 : depth - 1;
+    }
+    out += char;
+  }
+  return out;
+}
+
+function bySourceOrder(a: DynamicUsage | KeyUsage, b: DynamicUsage | KeyUsage): number {
+  return a.line - b.line || a.column - b.column;
+}
+
 function positionOf(source: string, index: number): { line: number; column: number } {
   let line = 1;
   let lineStart = 0;

package/src/index.ts

@@ -55,6 +55,7 @@ export {
   catalogMissingKeys,
   catalogsNeverRegistered,
   catalogUnregistered,
+  familyIncomplete,
   I18N_ERROR_CODES,
   I18N_ERROR_TITLES,
   I18nError,
@@ -77,6 +78,7 @@ export {
 } from './extract';
 export { FRAMEWORK_CATALOG } from './framework';
 export {
+  familyStems,
   type InterpolationValue,
   type InterpolationVars,
   interpolate,
@@ -85,6 +87,7 @@ export {
   pluralCategory,
   pluralKeyCandidates,
   pluralVariantsOf,
+  selectMessageKey,
   selectPluralKey,
 } from './interpolate';
 export {
@@ -104,6 +107,11 @@ export {
   parseAcceptLanguage,
   SUPPORTED_LOCALES,
 } from './locales';
+export {
+  type RecordingTranslator,
+  recordingTranslator,
+  type TranslationMiss,
+} from './recording-translator';
 export {
   assertCatalogsRegistered,
   type CatalogRegistrationGap,

package/src/interpolate.ts

@@ -1,5 +1,5 @@
 /**
- * `{var}` substitution and CLDR plural-form selection.
+ * `{var}` substitution and key selection: CLDR plurals, ordinals and `select` families.
  * Pure string work: it never reads a catalog and never resolves a locale.
  */
 
@@ -103,12 +103,85 @@ export function selectPluralKey(
   return key;
 }
 
+/** A `select` value that can be part of a key: anything else selects nothing, never a stray key. */
+const SELECT_VALUE = /^[A-Za-z0-9-]{1,32}$/;
+
+/**
+ * The family stems `t(key, { select, ordinal })` reads, most specific first: `select` picks
+ * `<key>_select_<value>` then `<key>_select_other`; `ordinal` picks `<key>_ordinal_<category>` (CLDR's
+ * ORDINAL rules: `en` 1 one, 2 two, 3 few, 4 other, 11 other) then `<key>_ordinal_other`. Both
+ * compose, select outermost: `invite_select_female_ordinal_one`. Empty when neither var selects.
+ */
+export function familyStems(
+  key: string,
+  vars: InterpolationVars | undefined,
+  locale: string,
+): string[] {
+  const select = vars?.['select'];
+  const ordinal = vars?.['ordinal'];
+  const selects = typeof select === 'string' && SELECT_VALUE.test(select);
+  const ordinals = typeof ordinal === 'number' && Number.isFinite(ordinal);
+  if (!selects && !ordinals) return [];
+  let stems = [key];
+  if (selects) stems = [...new Set([`${key}_select_${select}`, `${key}_select_other`])];
+  if (ordinals) {
+    const category = ordinalRulesFor(locale).select(ordinal);
+    stems = stems.flatMap((stem) => [
+      ...new Set([`${stem}_ordinal_${category}`, `${stem}_ordinal_other`]),
+    ]);
+  }
+  return stems;
+}
+
+/**
+ * The catalog entry one `t(key, vars)` reads. The ONE selection: `t()` and `recordingTranslator`
+ * both call it, so a new selecting var is added here and neither can answer differently. A family
+ * (`select`, `ordinal`) is asked first, each stem with `count`'s plural chain when there is one; a
+ * family the catalog does not define falls through to the key's own plural, as before.
+ */
+export function selectMessageKey(
+  key: string,
+  vars: InterpolationVars | undefined,
+  locale: string,
+  has: (candidate: string) => boolean,
+): string {
+  const count = vars?.['count'];
+  const counted = typeof count === 'number' && Number.isFinite(count);
+  const first = (stems: readonly string[]): string | undefined => {
+    for (const stem of stems) {
+      const found = (counted ? pluralKeyCandidates(stem, count, locale) : [stem]).find(has);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  const family = first(familyStems(key, vars, locale));
+  if (family !== undefined) return family;
+  const own = counted ? selectPluralKey(key, count, locale, has) : key;
+  if (has(own)) return own;
+  // `Translator.has()` is true on `_select_other`/`_ordinal_other` alone, so a guarded `t(key)`
+  // without (or with an unusable) family var reaches them last — never a ⟦key⟧ after the guard.
+  return first([`${key}_select_other`, `${key}_ordinal_other`]) ?? own;
+}
+
 /** All suffixed variants of `key` a locale could legitimately define. */
 export function pluralVariantsOf(key: string): string[] {
   return [`${key}_plural`, ...PLURAL_CATEGORIES.map((category) => `${key}_${category}`)];
 }
 
 const rulesCache = new Map<string, Intl.PluralRules>();
+const ordinalCache = new Map<string, Intl.PluralRules>();
+
+/** `pluralRulesFor`'s bound and canonical key, for CLDR's ordinal rules: "1st", "2nd", "3rd". */
+function ordinalRulesFor(locale: string): Intl.PluralRules {
+  const tag = canonicalLocale(locale) ?? 'en';
+  return cachedFormatter(ordinalCache, tag, () => {
+    try {
+      return new Intl.PluralRules(tag, { type: 'ordinal' });
+    } catch {
+      return new Intl.PluralRules('en', { type: 'ordinal' });
+    }
+  });
+}
 
 /**
  * Bounded and canonically keyed, because `locale` reaches here from an `Accept-Language` header

package/src/recording-translator.ts

@@ -0,0 +1,61 @@
+/**
+ * A translator that remembers what it could not answer, for a surface that refuses rather than
+ * shows `⟦key⟧`: a mail cannot be taken back. It reads the render's own facts, never the bytes,
+ * because user data may hold a `⟦`.
+ */
+
+import { placeholdersOf, selectMessageKey } from './interpolate';
+import { isMiss, type TranslateVars, type Translator } from './translator';
+
+/** One thing a render asked for and could not fill. A `slot` names a `{var}` of a key that exists. */
+export interface TranslationMiss {
+  readonly key: string;
+  readonly slot?: string | undefined;
+}
+
+export interface RecordingTranslator {
+  readonly t: Translator;
+  /** Distinct misses so far, sorted: a key may be rendered more than once. */
+  misses(): readonly TranslationMiss[];
+}
+
+/**
+ * Picks the template through `selectMessageKey`, the selector `t()` itself uses, because `has()` is
+ * too coarse to decide on: it says yes for a plural family read without a `count`, where `t()`
+ * renders `⟦key⟧`. A value that is itself a marker is a miss too: it is what `x i18n sync` seeds, so
+ * following a refusal's own fix must not be what delivers the brackets.
+ */
+export function recordingTranslator(base: Translator): RecordingTranslator {
+  const misses = new Map<string, TranslationMiss>();
+  const note = (key: string, slot?: string): void => {
+    misses.set(slot === undefined ? key : `${key}{${slot}}`, { key, slot });
+  };
+  const exists = (candidate: string): boolean => base.raw(candidate) !== undefined;
+
+  const inspect = (key: string, vars: TranslateVars | undefined): void => {
+    const template = base.raw(selectMessageKey(key, vars, base.locale, exists));
+    if (template === undefined || isMiss(template)) {
+      note(key);
+      return;
+    }
+    for (const slot of placeholdersOf(template)) {
+      if (vars === undefined || !Object.hasOwn(vars, slot) || vars[slot] === undefined) {
+        note(key, slot);
+      }
+    }
+  };
+
+  const t: Translator = Object.assign(
+    (key: string, vars?: TranslateVars): string => {
+      inspect(key, vars);
+      return base(key, vars);
+    },
+    { has: base.has, raw: base.raw, keys: base.keys, locale: base.locale },
+  );
+
+  return {
+    t,
+    misses: () =>
+      [...misses.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, miss]) => miss),
+  };
+}

package/src/translator.ts

@@ -6,12 +6,16 @@
 
 import { DEFAULT_LOCALE } from '@ultimat3/core';
 import type { Catalog } from './catalog';
-import { type InterpolationVars, interpolate, selectPluralKey } from './interpolate';
+import { type InterpolationVars, interpolate, selectMessageKey } from './interpolate';
 import type { Locale } from './locales';
 
 export interface TranslateVars extends InterpolationVars {
   /** Present ⇒ plural selection runs against the locale's CLDR categories. */
   count?: number;
+  /** Present ⇒ `<key>_ordinal_<category>` by CLDR's ordinal rules, then `<key>_ordinal_other`. */
+  ordinal?: number;
+  /** Present ⇒ `<key>_select_<value>`, then `<key>_select_other`: gender, role, any closed set. */
+  select?: string;
 }
 
 /** Suffixes `selectPluralKey` probes: the CLDR categories plus the two-form shortcut. */
@@ -22,6 +26,13 @@ type PluralStem<TKey extends string> = TKey extends `${infer TStem}_${PluralSuff
   ? TStem
   : never;
 
+/** `invite_select_female_one` → `invite`; `place_ordinal_two` → `place`. */
+type FamilyStem<TKey extends string> = TKey extends `${infer TStem}_select_${string}`
+  ? TStem
+  : TKey extends `${infer TStem}_ordinal_${string}`
+    ? TStem
+    : never;
+
 /** Recursion budget — an unresolved generic catalog would otherwise never bottom out. */
 type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7];
 
@@ -30,7 +41,7 @@ type CatalogPaths<TCatalog, TDepth extends number = 8> = [Depth[TDepth]] extends
   ? never
   : {
       [TKey in keyof TCatalog & string]: TCatalog[TKey] extends string
-        ? TKey | PluralStem<TKey>
+        ? TKey | PluralStem<TKey> | FamilyStem<TKey>
         : `${TKey}.${CatalogPaths<TCatalog[TKey], Depth[TDepth]> & string}`;
     }[keyof TCatalog & string];
 
@@ -56,21 +67,13 @@ export interface Translator<TCatalog = Catalog> {
 export function catalogTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOCALE): Translator {
   const hasExact = (key: string): boolean => Object.hasOwn(catalog, key);
 
-  const resolveKey = (key: string, vars?: TranslateVars): string => {
-    const count = vars?.count;
-    if (typeof count === 'number' && Number.isFinite(count)) {
-      return selectPluralKey(key, count, locale, hasExact);
-    }
-    return key;
-  };
-
   const translate = (key: string, vars?: TranslateVars): string => {
     // Through `hasExact`, never a raw index: a key travels as data (`t(row.labelKey)`), and on a
     // `{}`-prototyped catalog `catalog['valueOf']` resolves to the INHERITED function instead of
     // reading as absent — so `interpolate` threw on a non-string, `t('constructor')` returned a
     // function through a signature typed `string`, and `isMiss(t('__proto__'))` threw on an object.
     // Catalogs are null-prototyped now; this guard is what makes that true of any catalog.
-    const resolved = resolveKey(key, vars);
+    const resolved = selectMessageKey(key, vars, locale, hasExact);
     const template = hasExact(resolved) ? catalog[resolved] : undefined;
     if (template === undefined) return `⟦${key}⟧`;
     // Always, never only when `vars` was passed: skipping it made `t('a')` and `t('a', {})` two
@@ -85,7 +88,9 @@ export function catalogTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOC
       hasExact(key) ||
       hasExact(`${key}_other`) ||
       hasExact(`${key}_plural`) ||
-      hasExact(`${key}_one`),
+      hasExact(`${key}_one`) ||
+      hasExact(`${key}_select_other`) ||
+      hasExact(`${key}_ordinal_other`),
     raw: (key: string): string | undefined => (hasExact(key) ? catalog[key] : undefined),
     keys: (): string[] => Object.keys(catalog).sort(),
     locale,