suaveplan/openspec/archive/2026-05-09-i18n-icu-parser/proposal.md

# `@suaveplan/i18n-icu-parser` — ICU parser, interpolation, pluralization

**Package**: `@suaveplan/i18n-icu-parser` (NEW)
**Status**: PROPOSED
**Type**: feature (new universal-tier package; verbatim port + tiny DI wedge)
**Date**: 2026-05-05
**Wave**: 2 (depends on Wave 1 foundation; required by Wave 6 core slim)
**Design doc**: `openspec/cross-cutting-designs/2026-05-05-i18n-modular-split.md` (especially §5b)
**Path**: `packages/i18n/i18n-icu-parser/`

## Why

The ICU MessageFormat parser, the `{{var}}` interpolation engine, and the 9-language plural-rule table currently live in three separate folders inside the `@suaveplan/i18n` monolith:

- `src/parser/message/` — AST + parser + renderer for ICU `{var, number, integer}`, `{count, plural, one{..} other{..}}`, `{kind, select, foo{..} other{..}}`
- `src/core/interpolation/` — `{{varname}}` substitution engine with `escapeHtmlChars`, `escapeRegex`, depth-limit guard
- `src/core/pluralization/` — `arabicPlural`, `englishPlural`, etc. (9 plural-rule functions matching CLDR categories)

These three modules have a single coherent purpose: **turn a localized template + values into a final string**. They share the `MessageNode` AST, the depth-limit invariant, the `INTERPOLATION_ERROR` / `PLURAL_RULE_NOT_FOUND` / `NESTING_DEPTH_EXCEEDED` error codes, and the same test fixtures. Splitting them into separate packages would fragment the seam without benefit. Bundling them as `@suaveplan/i18n-icu-parser` keeps the AST internal to one package and exposes a clean public surface (`MessageParser`, `InterpolationEngine`, `PluralizationEngine`, `renderNodes`) for the slim core to compose.

The one architectural wedge: today `parser/message/message-render.ts` imports `formatNumber` / `formatCurrency` / `formatDate` / `formatTime` directly. That would force the parser to depend on the formatter packages and invert Waves 2 and 3. The fix is a small DI seam: the parser declares a `FormatBridge` interface; the slim core wires up the bridge with the actual formatter packages in Wave 6. See §5b of the design doc.

## What changes

### New package: `@suaveplan/i18n-icu-parser`

- ADDED: `packages/i18n/i18n-icu-parser/` package scaffold (package.json, tsconfig.json, vite.config.ts, README.md).
- ADDED: `src/parser/message.ts` — `MessageParser` class, `extractVariables`, `MessageNode` AST. Source: `packages/i18n/i18n/src/parser/message/message.ts` verbatim.
- ADDED: `src/parser/message-render.ts` — `renderNodes` function. Source: `packages/i18n/i18n/src/parser/message/message-render.ts`. **Modified**: replaces direct `formatNumber` / `formatCurrency` / `formatDate` / `formatTime` imports with calls to a `FormatBridge` parameter on `RenderOptions`; provides a no-Intl fallback when bridge is undefined.
- ADDED: `src/parser/format-bridge.ts` — declares the `FormatBridge` interface (see design doc §5b) plus a `noopFormatBridge: FormatBridge` that coerces values to string (used by the parser's own tests; consumers in production wire a real bridge).
- ADDED: `src/parser/message.types.ts` — `MessageNode`, `PlainNode`, `VarNode`, `FormatNode`, `PluralNode`, `SelectNode`, `RenderOptions`, etc.
- ADDED: `src/parser/index.ts` — explicit named re-exports.
- ADDED: `src/interpolation/interpolation.ts` — `InterpolationEngine` class. Source: `packages/i18n/i18n/src/core/interpolation/interpolation.ts` verbatim minus the formatter imports (which were unused at the engine level).
- ADDED: `src/interpolation/interpolation.types.ts` — `InterpolationConfig`, `InterpolationOptions`, `InterpolationResult`, `InterpolationValues`, `ValueFormatter`.
- ADDED: `src/interpolation/escape-html.ts` — `escapeHtmlChars` standalone helper.
- ADDED: `src/interpolation/escape-regex.ts` — `escapeRegex` standalone helper.
- ADDED: `src/interpolation/index.ts` — explicit named re-exports.
- ADDED: `src/pluralization/pluralization.ts` — `PluralizationEngine` class + 9 plural-rule functions: `arabicPlural`, `englishPlural`, `welshPlural`, `russianPlural`, `polishPlural`, `chinesePlural`, `japanesePlural`, `frenchPlural`, `germanPlural`. Source: `packages/i18n/i18n/src/core/pluralization/pluralization.ts` verbatim.
- ADDED: `src/pluralization/pluralization.types.ts` — `PluralCategory` (`"zero" | "one" | "two" | "few" | "many" | "other"`), `PluralRuleFunction`, `PluralizationConfig`.
- ADDED: `src/pluralization/index.ts` — explicit named re-exports.
- ADDED: `src/index.ts` — explicit named re-exports of the three sub-namespaces.

### Subpath exports

- `.` — root barrel
- `./parser` — parser + render + format-bridge + types
- `./parser/format-bridge` — `FormatBridge` interface + `noopFormatBridge` only (single-import for slim-core wiring)
- `./interpolation` — interpolation engine + helpers + types
- `./pluralization` — `PluralizationEngine` + every plural-rule function + types

### Dependencies

- `@suaveplan/i18n-shared workspace:^` — for `I18N_CODES`, `I18nError`, `DEFAULT_INTERPOLATION`
- `@suaveplan/types workspace:^` — for shared catalog types if referenced
- `@suaveplan/error workspace:^` — for `defineCodes` consumer-side helpers (if any)
- `@opentelemetry/api catalog:observability` — for histogram emission in `MessageParser.parse` and `InterpolationEngine.interpolate`
- `tslib catalog:build`
- `zod catalog:forms` — for `InterpolationConfigSchema` boundary validation
- **No** dep on any formatter package, on `@suaveplan/i18n` core, or on `@suaveplan/i18n-detector`.

## Out of scope

- **Removing parser / interpolation / pluralization from `packages/i18n/i18n/src/`** — happens in Wave 6 (`i18n-core-slim`). For Waves 2–5, both copies coexist; the monolith remains green.
- **Backwards-compatible bridge implementation in the slim core** — that lives in Wave 6's change folder.
- **CLDR data import for additional plural rules** beyond the existing 9 — out of scope; new rules can be added in a follow-up.
- **Switching from hand-rolled MessageFormat parser to `intl-messageformat`** — explicit non-goal; the existing parser passes ICU conformance tests and avoids the 39 KiB external dep.
- **Async interpolation** — current engine is synchronous; async (e.g. for Promise-returning value resolvers) is a follow-up.

## Source mapping

| Requirement | Source file | Source lines | Notes |
|---|---|---|---|
| `MessageParser`, `extractVariables`, `MessageNode` AST | `packages/i18n/i18n/src/parser/message/message.ts` | full file | Verbatim port |
| `renderNodes` | `packages/i18n/i18n/src/parser/message/message-render.ts` | full file | Port; replace direct formatter imports with `FormatBridge` parameter |
| `MessageNode`, `PlainNode`, `VarNode`, `FormatNode`, `PluralNode`, `SelectNode`, `RenderOptions` types | `packages/i18n/i18n/src/parser/message/message.types.ts` | full file | Verbatim port |
| `InterpolationEngine` | `packages/i18n/i18n/src/core/interpolation/interpolation.ts` | full file minus formatter imports | Verbatim port |
| `escapeHtmlChars`, `escapeRegex` | `packages/i18n/i18n/src/core/interpolation/interpolation.ts` | matching exports | Split into per-helper files for tree-shaking |
| `InterpolationConfig`, `InterpolationOptions`, `InterpolationResult`, `InterpolationValues`, `ValueFormatter` types | `packages/i18n/i18n/src/core/interpolation/interpolation.types.ts` | full file | Verbatim port |
| `PluralizationEngine` + 9 plural-rule functions | `packages/i18n/i18n/src/core/pluralization/pluralization.ts` | full file | Verbatim port |
| `PluralCategory`, `PluralRuleFunction`, `PluralizationConfig` types | `packages/i18n/i18n/src/core/pluralization/pluralization.types.ts` | full file | Verbatim port |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `FormatBridge` interface | New DI seam — see design doc §5b. Required so the parser package does not depend on formatter packages |
| `noopFormatBridge: FormatBridge` | Tests need a no-op bridge; consumers without Intl wrappers also benefit |
| Subpath export `./parser/format-bridge` | Slim-core wiring imports only this one file when constructing the default bridge |

## Verification approach

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

- `packages/i18n/i18n-icu-parser/src/parser/message.test.ts` — every ICU node type round-trips through parse + render; conformance with the existing monolith's parser test suite (verbatim test port)
- `packages/i18n/i18n-icu-parser/src/parser/message-render.test.ts` — `renderNodes` calls `formatBridge.number/currency/date/time/relativeTime` when supplied; falls back to `String(value)` when bridge is undefined; throws `INTERPOLATION_ERROR` on missing variable
- `packages/i18n/i18n-icu-parser/src/parser/format-bridge.test.ts` — `noopFormatBridge` returns string-coerced values for every method
- `packages/i18n/i18n-icu-parser/src/interpolation/interpolation.test.ts` — basic substitution, custom delimiters, depth-limit enforcement (`NESTING_DEPTH_EXCEEDED`), HTML escape on/off
- `packages/i18n/i18n-icu-parser/src/interpolation/escape-html.test.ts` — `<`, `>`, `&`, `"`, `'` all escaped
- `packages/i18n/i18n-icu-parser/src/interpolation/escape-regex.test.ts` — every regex meta char escaped
- `packages/i18n/i18n-icu-parser/src/pluralization/pluralization.test.ts` — every one of the 9 rule functions returns the correct CLDR category for boundary values; `PLURAL_RULE_NOT_FOUND` thrown for unknown locale; Welsh's six-form rule covered
- `packages/i18n/i18n-icu-parser/src/index.test.ts` — every documented export resolves through the root barrel
- Conformance test pass rate on the existing `packages/i18n/i18n/src/conformance.test.ts` — must remain 100% after Wave 6 wires the bridge through

## Impact

- New universal-tier package — joins `@suaveplan/i18n-shared` under `packages/i18n/`.
- `@suaveplan/i18n` slim core (Wave 6) consumes this package and wires `FormatBridge` against the formatter packages.
- No downstream consumer changes needed — the slim core re-export bridge surfaces every public symbol from this package under the `@suaveplan/i18n` root.
- `MANIFEST.md` and `CLAUDE.md` updated.