suaveplan/openspec/changes/archive/2026-05-04-i18n-completion/proposal.md

# i18n completion — ergonomic t(), full ICU, plugin surface, Intl wrappers

**Package**: `@suaveplan/i18n`
**Status**: PROPOSED
**Type**: feature + spec-conformance
**Date**: 2026-05-04

## Why

A 2026-05-04 review against `i18next`, `FormatJS / react-intl`, `LinguiJS`, `vue-i18n`, and `next-intl` flagged a long tail of features that are headline-tier in every popular i18n library and missing here. The package today is a clean, well-tested **core** — but the surface that consumers actually call (`MessageCatalog`, `InterpolationEngine`, `PluralizationEngine`, `MessageParser`) requires three separate manual calls to do what `i18next.t('item', { count: 3 })` does in one. It also lacks a formal plugin lifecycle, three of four `Intl.*` wrappers, and several real-world ICU MessageFormat features (typed args, apostrophe escape, rich-text/tag interpolation). OTel meter instruments are defined but never incremented.

This change closes those gaps so `@suaveplan/i18n` is genuinely on par with i18next in features, with the genesis-quality surface (Zod-validated, generic-threaded, OTel-wired, 100/100/100/100). It pairs with `i18n-storage-backends` (which adds the `Backend` interface) and is a prerequisite for `enterprise-react-i18n`.

## What changes

### 1. Ergonomic `t()` — one-call translate

The current `MessageCatalog.t(key)` returns the raw catalog string. Consumers manually wire pluralization + interpolation + missing-key handling. This is the biggest DX gap vs every popular library.

- ADDED: `MessageCatalog.t(key, options?: TranslateOptions)` accepts a single options bag that internally resolves plural + interpolation + nested-key references + context selector + default value:
  - `count: number` — when present, runs `PluralizationEngine.resolve` and selects the matching plural form. The catalog key may be a plain string or an object `{ one, other, ... }`; both shapes work.
  - `context: string` — i18next-compatible context selector. `t('greeting', { context: 'male' })` looks up `greeting_male` first, falling back to `greeting`.
  - `defaultValue: string` — fallback when key is missing, in lieu of returning the key.
  - `values: Record<string, unknown>` — interpolation values; `count` is auto-injected so plural strings can use `{count}` directly.
  - `escapeHtml?: boolean` — overrides the engine default for this call.
  - `formatters?: Record<string, ValueFormatter>` — per-call formatter overrides.
  - Nested-key references in source strings: `"$t(common:cancel)"` resolves to the value of `common:cancel` recursively; cycle detection via depth limit.
- ADDED: `TranslateOptions` and `PluralKey` types in `src/core/catalog/translate.types.ts`.
- ADDED: `t.plural(key, count, values?)` shortcut for the common case.
- MODIFIED: existing `MessageCatalog.t(key)` single-string call remains backwards-compatible — `t(key)` is `t(key, {})`.

### 2. Full ICU MessageFormat support

The current `MessageParser` handles `{name}`, `{count, plural, ...}`, `{gender, select, ...}`. Real ICU (and FormatJS) callers expect more.

- ADDED: `selectordinal` node type — `{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`. Routes through `PluralizationEngine` with `ordinal: true`.
- ADDED: typed argument support: `{date, date, short}`, `{at, time, medium}`, `{n, number, currency/USD}`, `{n, number, percent}`, `{n, number, ::compact-short}` (ICU number skeleton). Wired through `formatDate` / `formatNumber` / `formatTime` from `@suaveplan/i18n/formatting/*`.
- ADDED: apostrophe quoting — `it''s` renders as `it's`; `'{literal}'` renders as `{literal}` (skips ICU parsing inside single-quoted runs). This is the standard ICU MessageFormat quoting rule and the current parser silently misparses these strings.
- ADDED: rich-text / tag interpolation — `'<bold>welcome</bold>'` parses to a `TagNode` AST; `MessageParser.format(message, values)` accepts `values: { bold: (chunks) => string }` to produce a string, and `MessageParser.formatChunks(message, values, chunkValues)` returns `Array<string | T>` for React/Vue consumers (where `chunkValues` like `{ bold: (chunks) => <b>{chunks}</b> }` produce framework nodes — used heavily by `enterprise-react-i18n`).
- ADDED: `MessageNode` discriminated union expands: `text | variable | plural | selectordinal | select | tag | typed-argument`.
- ADDED: ICU validator — `MessageParser.validate(message): ValidationResult` reports unbalanced braces, missing `other` branches, undefined plural categories, and unknown typed-argument types. Used by the optional build-time linter.

### 3. Formal plugin / extensibility surface

Today's "extensibility" is informal: `addFormatter`, `registerRule`, etc. on individual engines. There's no plugin lifecycle and no event bus, which makes cross-cutting concerns (logging, missing-key reporters, post-processors) hard to wire.

- ADDED: `I18nPlugin` interface in `src/core/plugin/plugin.types.ts`:
  - `name: string`, `version?: string`
  - `install?(i18n: I18nInstance): void | Promise<void>` — register hooks, formatters, backends
  - `dispose?(): void | Promise<void>` — teardown
  - Plugin types (a single plugin can implement multiple): `'backend' | 'formatter' | 'post-processor' | 'detector' | 'logger'`
- ADDED: `I18nInstance` — a top-level façade that binds together `MessageCatalog`, `InterpolationEngine`, `PluralizationEngine`, `MessageParser`, `LocaleResolver`, and the plugin registry. Created via `createI18n(options)`. Existing engines remain individually constructable.
- ADDED: Event bus topics on `I18nInstance` (delegates to `@suaveplan/events`):
  - `languageChanged` — `{ from, to }`
  - `loaded` — `{ locale, namespace, backend? }`
  - `missingKey` — `{ locale, namespace, key, defaultValue? }`
  - `keyAdded` — `{ locale, namespace, key, value }` (for HMR / save-missing flows)
  - `pluralRuleAdded` — `{ locale }`
- ADDED: post-processor plugins. `I18nInstance` accepts `postProcessors: PostProcessor[]` where each is `(value, key, options) => string`. Built-in post-processors: `markdown` (renders bold/italic/links via `marked` peer), `sprintf` (printf-style format strings — opt-in i18next compatibility), `pseudo-localization` (transforms `Welcome` → `[!! Wëlçömé !!]` for layout testing).
- ADDED: detector plugins (browser-side locale detection). Built-in detectors: `navigator-detector`, `localstorage-detector`, `cookie-detector`, `query-detector`, `path-detector`, `subdomain-detector`. Browser `LocaleResolver` composes them via `detectionOrder`. Server-side `createLocaleMiddleware` already covers the equivalent surface.

### 4. Missing Intl wrappers — list, display-names, expanded number helpers

The current `formatting/` module exposes `currency`, `date`, and (after `i18n-formatters` lands) `number` and `relative-time`. Two more `Intl.*` APIs are still unwrapped, and three convenience number helpers are universally expected.

- ADDED: `formatList(values, locale, options?)` — wraps `Intl.ListFormat`. Options: `style: 'long' | 'short' | 'narrow'`, `type: 'conjunction' | 'disjunction' | 'unit'`. Per-(locale, options) cache like the other formatters.
- ADDED: `formatDisplayName(code, locale, options)` — wraps `Intl.DisplayNames`. Options: `type: 'language' | 'region' | 'script' | 'currency' | 'calendar' | 'dateTimeField'`, `style`, `fallback`. Use cases: building locale switchers, currency dropdowns, region pickers.
- ADDED: `formatPercent(value, locale, options?)` — pre-bound `formatNumber({ style: 'percent' })`.
- ADDED: `formatCompact(value, locale, options?)` — pre-bound `formatNumber({ notation: 'compact' })` for "1.2K" / "1.2M" output.
- ADDED: `formatUnit(value, unit, locale, options?)` — pre-bound `formatNumber({ style: 'unit', unit })` for "12 km/h" output.

### 5. Locale + plural correctness fixes

- MODIFIED: `parseAcceptLanguage` preserves script-subtag casing (`zh-Hant-TW`, not `zh-hant-tw`) per BCP-47. The current implementation lowercases the entire tag.
- MODIFIED: `PluralizationEngine` defaults to `Intl.PluralRules` first, falls back to the hand-written rule registry. The hand-written rules drift against CLDR over time; making `Intl.PluralRules` the primary source future-proofs against CLDR releases. Hand-written rules remain registered as overrides for runtimes that lack `Intl.PluralRules` (e.g. very old browsers — vanishingly rare in genesis, but the override path costs nothing).
- ADDED: `Intl.Locale.weekInfo`-aware `getDayNames(locale, style?)` — first-day-of-week is consulted via `new Intl.Locale(locale).weekInfo.firstDay` (1 = Monday, 7 = Sunday). Falls back to Monday when `weekInfo` is unavailable. Existing Monday-hardcoded behaviour was a bug for US/Mid-East locales.
- ADDED: `formatSegment(text, locale, granularity?)` and `compareLocale(a, b, locale, options?)` — thin wrappers around `Intl.Segmenter` and `Intl.Collator` for non-Latin search/sort.
- ADDED: `pseudoLocalize(text, options?)` post-processor with three modes: `accent` (`Welcome` → `Wéłçömé`), `bracket` (`Welcome` → `[!! Welcome !!]`), `expand` (Welcome → `Welcomeeeee` to test layout). Used by the `pseudo-localization` post-processor plugin and by tests directly.

### 6. Wire OTel meter instruments

`getI18nMetrics()` exists with `translateTotal`, `localeResolveTotal`, `translateDuration` instruments (`src/observability/metrics.ts`), but no production code path increments them. They are dead code today.

- MODIFIED: `MessageCatalog.get` increments `i18n.translate.total{outcome,locale}` on every call and records `i18n.translate.duration_ms{locale}` for every lookup.
- MODIFIED: `LocaleResolver.resolve` and `negotiateLocale` increment `i18n.locale.resolve.total{strategy,locale}`.
- ADDED: `i18n.interpolation.duration_ms` histogram on `InterpolationEngine.render` and `MessageParser.format`.
- ADDED: `i18n.missing_key.total` counter labelled by `locale`, `namespace` — incremented from `MessageCatalog.get` whenever the lookup falls through to the missing-key handler or returns `undefined`.

### 7. Workflow tooling

- ADDED: missing-key reporter plugin — `createMissingKeyReporter({ logger?, onMissing? })` registers as an `I18nPlugin` and listens on the `missingKey` event. Default behaviour: log via `@suaveplan/logger` at `warn` level. With a backend configured, it can also call `catalog.saveMissing` (gated by `saveMissing: true`).
- ADDED: `extractKeys(source: string, options?)` — minimal AST-free extractor that walks a source string for `t('...')` / `t("...")` / `<Trans i18nKey="...">` patterns and returns the deduplicated key list. Not a full TypeScript parser; intended for the simple case and used by the optional `extract-i18n` CLI in `i18n-tooling` (separate change).
- ADDED: pseudo-localization post-processor (covered by §5) wired so consumers can flip `i18n.use(pseudoLocalizationPlugin())` in test environments.

## Out of scope

- **Full TypeScript-AST key extractor** — separate `i18n-tooling` change once the runtime surface stabilises.
- **PO / XLIFF / Android XML / iOS .strings round-trip** — the `MultiFileFsBackend` (in `i18n-storage-backends`) already supports PO read via the `gettext-parser` peer; full bidirectional XLIFF / Android XML tooling is a separate change.
- **Lingui/FBT-style hash-based stable IDs** — separate change. Requires build-time tooling and a different runtime contract.
- **React/Vue/Solid bindings** — covered by `enterprise-react-i18n` (and equivalents for other frameworks as they land).
- **Build-time message compilation (FormatJS-style)** — separate change once we have a Vite plugin scoped.

## Source mapping

This change is **genesis-original** in spirit: it lifts feature parity from i18next + FormatJS rather than from `../suaveplan/enterprise/i18n.md`. Every requirement below has a feature-parity citation in the table.

### Feature-parity table

| Requirement | Reference | Notes |
|---|---|---|
| Ergonomic `t({ count, context, defaultValue, values, ... })` | i18next `t()` | Single most-used i18n API; matching shape is critical for consumer ergonomics. |
| Nested-key references `$t(...)` | i18next nesting | Cycle detection via depth limit (default 4). |
| `selectordinal` node | ICU MessageFormat | Already supported by `PluralizationEngine.resolve(..., { ordinal: true })`; missing only in the parser. |
| Typed arguments (`{x, number, currency/USD}`) | ICU MessageFormat / FormatJS | Routes through existing formatters. |
| Apostrophe quoting | ICU MessageFormat spec | Current parser silently misparses these — it's a bug, not a feature. |
| Tag/rich-text interpolation | i18next `<Trans>`, FormatJS `<FormattedMessage>` | Required by `enterprise-react-i18n`. |
| `I18nPlugin` interface + lifecycle | i18next plugin model | Genesis already uses this pattern in `@suaveplan/network`, `@suaveplan/drive`. |
| Event bus topics | i18next emit | Reuses `@suaveplan/events`. |
| Pseudo-localization | i18next-pseudo, FormatJS pseudo | Standard layout-testing tool. |
| `formatList`, `formatDisplayName` | `Intl.ListFormat`, `Intl.DisplayNames` | Universally expected. |
| `formatCompact`, `formatPercent`, `formatUnit` | Intl helpers | Convenience over `formatNumber`. |
| `Intl.Locale.weekInfo` for first-day-of-week | MDN, Chromium 99+, Node 22+ | Current Monday hardcode is a bug. |
| `Intl.PluralRules` first | CLDR drift hardening | Hand-written rules become overrides, not source of truth. |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| OTel `i18n.translate.total` etc. wiring | `i18n-spec-conformance` declared the instruments; this change actually increments them. AGENTS.md §13 row 4. |
| `extractKeys(source)` runtime helper | Enables a downstream CLI without locking the runtime to a specific TS-AST library. |
| `formatSegment` / `compareLocale` | Required for non-Latin search/sort in our search packages. |

## Verification approach

Each requirement carries a `**Verified by:**` line in the spec delta.

- `packages/i18n/i18n/src/core/catalog/translate.test.ts` — ergonomic `t()` with count, context, defaultValue, nested refs
- `packages/i18n/i18n/src/parser/message/message.test.ts` (extended) — selectordinal, typed args, apostrophe escape, tag nodes
- `packages/i18n/i18n/src/parser/message/message-validate.test.ts` — `MessageParser.validate` happy/sad paths
- `packages/i18n/i18n/src/core/plugin/plugin.test.ts` — `I18nPlugin` lifecycle, event bus topics, post-processor / detector composition
- `packages/i18n/i18n/src/formatting/list/list.test.ts`, `display-name/display-name.test.ts`, `number/number-helpers.test.ts`
- `packages/i18n/i18n/src/locale/segment/segment.test.ts`, `collator/collator.test.ts`
- `packages/i18n/i18n/src/observability/metrics.spec-conformance.test.ts` — every instrument records a sample under in-memory `MeterProvider`

## Migration impact

- `MessageCatalog.t(key)` (single-arg) — backwards-compatible. Existing call sites continue to work.
- `MessageCatalog.t(key, options)` (new) — additive.
- `parseAcceptLanguage` casing fix — observable change for consumers that string-compared the result. No genesis consumers depend on the lowercased tag (verified by grep).
- `PluralizationEngine` defaulting to `Intl.PluralRules` — observable for locales where the hand-written rule disagreed with CLDR. Tests pinning `Intl.PluralRules` output are added; the override registry path remains available for explicit overrides.
- `MessageParser` apostrophe handling — observable bug fix: `it''s` formerly rendered as `it''s` and now renders as `it's`. No genesis consumers depend on the broken behaviour (verified by grep).

### Affected dependents

`grep -rl "@suaveplan/i18n" /home/ubuntu/web/genesis/packages/ --include="package.json"` — only `packages/i18n/i18n/package.json` itself. New consumer (`@suaveplan/react-i18n`) lands via its own change.