OpenSpec Change: i18n-spec-conformance

Change ID: i18n-spec-conformance
Package: @suaveplan/i18n
Status: PROPOSED
Date: 2026-04-26
Reference: openspec/archive/2026-04-19-enterprise-i18n/specs/i18n/spec.md

Summary

Close the conformance gaps between the shipped @suaveplan/i18n package and its archived enterprise spec, and add type-level guarantees that make the package future-proof for consumers. The original change archived as "all tasks retroactively ticked" but several spec contracts are unimplemented or drifted: OTel instrumentation is absent, MessageCatalog lacks strict mode / loader dedup / namespace-aware set/load/keys / LookupResult.source, schemas don't match spec field names and aren't enforced at construction, InterpolationEngine never throws I18N.INTERPOLATION_ERROR, PluralizationEngine lacks strict mode and a CLDR-backed fallback, and LocaleResolver.normalizeLocaleCode accepts any string instead of validating BCP-47.

This change brings the package fully in line with the original spec, adds three type-safety upgrades (typed key inference via DotPaths<TMessages>, generic LookupResult<TLocale>, Intl.PluralRules fallback so new CLDR languages work without a code change), and re-establishes the 100/100/100/100 coverage gate.

Current-state audit

Spec ID	Requirement	Status
I18N-01	`I18nError` + 5 codes, side-effect register	✅ codes registered; ⚠️ no side-effect import in `src/index.ts`
I18N-02	Zod schemas match spec shape, parse at boundary	❌ field names drifted; ❌ never called at construction
I18N-03	`MessageCatalog` contract (`source`, `namespace`, strict, dedup, ns-aware `set`/`load`/`keys`)	❌ all missing
I18N-04	`InterpolationEngine` throws on unclosed delim / formatter error	❌ never throws
I18N-05	`PluralizationEngine` strict-mode throw	❌ missing
I18N-06	`MessageParser` AST + `extractVariables` + `renderNodes`	✅ shipped
I18N-07	Pluggable strategy chain, `ResolvedLocale.direction`, `INVALID_LOCALE` throw on garbage input	⚠️ chain lives in `middleware/server` (acceptable rename); ❌ `normalizeLocaleCode` never throws
I18N-08	Middleware attaches `ResolvedLocale`, sets `Content-Language`	⚠️ attaches result; missing `Content-Language` header path
I18N-09	Date formatting	✅ shipped
I18N-10	Currency formatting	✅ shipped
I18N-11	Utility functions	✅ shipped
I18N-12	OTel meter + counters + histogram	❌ entirely missing
I18N-13	Property tests	⚠️ inline in unit tests instead of `tests/properties/`
I18N-14	Per-component benchmarks	⚠️ bundled into single file
I18N-15	Hygiene (sideEffects, 100% coverage, no .skip/.only)	✅ shipped

New additions for this change

Type-level guarantees (future-proofing)

DotPaths<TMessages> template-literal type that recursively projects a nested TranslationRecord tree to its 'a.b.c' leaf paths.
MessageCatalog<TLocale, TMessages>.t<K extends DotPaths<TMessages> | (string & {})>(key: K) — autocomplete + compile-time key safety, with a string escape hatch.
LookupResult<TLocale extends string = string> carries the typed locale through.
PluralizationEngine falls back to Intl.PluralRules(locale).select(n) after locale-specific rule + base-language rule miss but before strict-mode throw, so CLDR drift no longer requires code changes for newly added languages.

OTel instrumentation

src/observability/metrics.ts exporting an i18nMetrics singleton built via getMeter('suaveplan.i18n'):

Counter i18n.translate.total — labels: outcome ('hit' | 'miss'), locale
Counter i18n.locale.resolve.total — labels: strategy, locale
Histogram i18n.translate.duration_ms — label: locale

Wired into MessageCatalog.get and detectLocale (locale middleware).

Strict mode + structured throws

MessageCatalog accepts strict?: boolean (default false); when on, missing keys throw I18nError(I18N.MISSING_KEY).
MessageCatalog.load(locale, namespace?, loader) now wraps loader rejections as I18nError(I18N.LOADER_FAILED) with the original error in cause.
MessageCatalog.load deduplicates concurrent calls for the same (locale, namespace) pair via an in-flight Map<string, Promise<void>>.
MessageCatalog.set(locale, namespace, record) and MessageCatalog.keys(locale, namespace?) accept a namespace argument.
LookupResult becomes { value: string | undefined; locale: TLocale; namespace: string; source: 'catalog' | 'fallback' | 'handler' | 'key' }.
InterpolationEngine throws I18nError(I18N.INTERPOLATION_ERROR) on unclosed delimiter and rethrows formatter exceptions with the same code wrapping the cause.
PluralizationEngine accepts strict?: boolean; when on, throws I18nError(I18N.PLURAL_RULE_NOT_FOUND) after rule + base-locale + Intl.PluralRules fallback all miss.
normalizeLocaleCode(code) validates a BCP-47-shaped tag (/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/) and throws I18nError(I18N.INVALID_LOCALE) otherwise.

Schema realignment

InterpolationConfigSchema → { open, close, escape, maxIterations } (renamed from prefix/suffix/escapeHtml/maxDepth). InterpolationEngine constructor accepts both shapes for one minor cycle, with the new shape canonical.
ResolverConfigSchema → { strategies: ResolutionStrategy[]; fallbackLocale: string; supportedLocales?: string[] }.
CatalogOptionsSchema adds strict?: boolean.
All three engines call .parse(options) in their constructor; failures throw I18nError with the relevant code and the Zod issue list in context.zodIssues.

Side-effect code registration

src/index.ts adds a top-level import './error-codes.js'; so consumers that import schemas only still trigger code registration.

Available workspace deps

Package	Available
`@suaveplan/error`	✅
`@suaveplan/types`	✅
`@opentelemetry/api` (catalog: `observability`)	✅

Impact

Breaking: LookupResult shape, InterpolationEngine option keys, MessageCatalog.load signature, MessageCatalog.addMessages renamed to set (alias retained for one cycle).
Version stays at 0.1.0 (genesis pre-1.0).
No external consumers on genesis yet; safe to land as-is.

6.3 KiB Raw Blame History