suaveplan/openspec/archive/2026-05-05-i18n-spec-conformance-followup/proposal.md

OpenSpec Change: i18n-spec-conformance-followup

• Change ID: i18n-spec-conformance-followup
• Package: @suaveplan/i18n
• Status: PROPOSED
• Date: 2026-05-04
• Reference: openspec/changes/archive/2026-05-04-i18n-spec-conformance/

Why

Three items were intentionally scoped out of i18n-spec-conformance because each requires a dedicated migration sweep. They are tracked here so the @suaveplan/i18n spec contract and runtime stay aligned.

Summary

• Wire engine-constructor option validation through .parse() so I18nError(I18N.INVALID_OPTIONS) carries context.zodIssues directly instead of through the hand-written mirror checks.
• Narrow MessageCatalog.t / .get to K extends DotPaths<TMessages> | (string & {}) and migrate every in-repo consumer signature.
• Move tests/property.test.ts into tests/properties/ and split src/__benchmarks__/i18n.bench.ts into catalog.bench.ts / interpolation.bench.ts / pluralization.bench.ts per I18N-13 / I18N-14.

Impact

• @suaveplan/i18n runtime constructors throw the same error class but with a richer context.zodIssues payload.
• Consumers that imported t(key: string) will see TypeScript flag unknown keys when TMessages is supplied; the (string & {}) escape hatch keeps existing string call-sites compiling.
• No public API removed; no change to dep graph.