suaveplan/openspec/archive/2026-05-09-i18n-core-slim/proposal.md

@suaveplan/i18n core slim — Wave 6 (destructive)

Package: @suaveplan/i18n (REWRITE — slim down) Status: PROPOSED Type: refactor (destructive — deletes ~70% of monolith source; full back-compat preserved via root barrel) Date: 2026-05-05 Wave: 6 (LAST — depends on Waves 1–5 having shipped and committed) Design doc: openspec/cross-cutting-designs/2026-05-05-i18n-modular-split.md (especially §8) Path: packages/i18n/i18n/

Why

Waves 1–5 ship every leaf package the modular split needs: foundation (@suaveplan/types/i18n + @suaveplan/i18n-shared), parser (@suaveplan/i18n-icu-parser), 8 formatter packages, 1 detector package, 5 backend packages. With those landed, the @suaveplan/i18n monolith becomes the integration layer: it owns only the catalog, the plugin slot (createI18n / I18nInstance), middleware, observability state, locale negotiation/resolver, the schemas, the keys utils, the missing-key flow, and the conformance test. Every other module has a new home — keeping the duplicate copies in the monolith creates a single-source-of-truth violation and undermines the per-package coverage gate.

This change deletes the moved-out modules, adds Waves 1–5 as workspace deps, and rewrites the root barrel so every public symbol that existed pre-split continues to resolve via re-export. The 745 existing tests in packages/i18n/i18n/src/conformance.test.ts and the 17 distinct downstream import paths from @suaveplan/react-i18n / react-ui / react-forms are the contract gates: every one must remain green after the slim. This is the only wave that touches packages/i18n/i18n/src/ destructively, and the only wave that can break downstream consumers — which is why it ships last, after every leaf package is on disk and committed.

What changes

@suaveplan/i18n (rewrite)

• ADDED: workspace-dep entries in packages/i18n/i18n/package.json dependencies:
  • @suaveplan/i18n-shared workspace:^
  • @suaveplan/i18n-icu-parser workspace:^
  • @suaveplan/i18n-formatter-number workspace:^
  • @suaveplan/i18n-formatter-relative-time workspace:^
  • @suaveplan/i18n-formatter-list workspace:^
  • @suaveplan/i18n-formatter-display-name workspace:^
  • @suaveplan/i18n-formatter-collator workspace:^
  • @suaveplan/i18n-formatter-segmenter workspace:^
  • @suaveplan/i18n-formatter-date workspace:^
  • @suaveplan/i18n-formatter-currency workspace:^
  • @suaveplan/i18n-detector workspace:^
  • @suaveplan/i18n-backend-memory workspace:^
  • @suaveplan/i18n-backend-http workspace:^
  • @suaveplan/i18n-backend-storage workspace:^
  • @suaveplan/i18n-backend-chained workspace:^
  • (@suaveplan/i18n-backend-fs-multifile workspace:^ is NOT added to universal-tier deps; it is server-tier and consumers import it directly. The slim core MAY add it as an optionalPeerDependency for documentation purposes.)
• REWRITTEN: packages/i18n/i18n/src/index.ts — root barrel becomes a re-export shim. Every one of the 33 export statements in the current 211-line barrel is preserved; the source of each export changes from local paths to the new packages. See "Back-compat re-export map" below for the exhaustive table.
• ADDED: packages/i18n/i18n/src/parser/format-bridge-default.ts — wires up a default FormatBridge (from @suaveplan/i18n-icu-parser/parser/format-bridge) by importing the formatter packages and binding their format<Name> functions. This bridge is passed to every MessageParser.render call inside MessageCatalog and I18nInstance. Consumers that construct createI18n(...) get formatters auto-wired; advanced consumers can pass { formatBridge: customBridge } to createI18n to override.
• MODIFIED: packages/i18n/i18n/src/core/catalog/catalog.ts and core/plugin/instance.ts — pass the default FormatBridge through every renderNodes call. No public API change; both classes already accept a RenderOptions shape; the bridge slot is added to that shape.

Files DELETED from packages/i18n/i18n/src/

The following directories and files are deleted because every symbol they export is now sourced from a new package:

Deleted path	New home (re-exported from)
src/constants/ (entire directory)	@suaveplan/i18n-shared/constants
src/error-codes.ts	@suaveplan/i18n-shared/errors
src/errors/ (entire directory)	@suaveplan/i18n-shared/errors
src/parser/ (entire directory)	@suaveplan/i18n-icu-parser/parser
src/core/interpolation/ (entire directory)	@suaveplan/i18n-icu-parser/interpolation
src/core/pluralization/ (entire directory)	@suaveplan/i18n-icu-parser/pluralization
src/formatting/number/	@suaveplan/i18n-formatter-number
src/formatting/relative-time/	@suaveplan/i18n-formatter-relative-time
src/formatting/list/	@suaveplan/i18n-formatter-list
src/formatting/display-name/	@suaveplan/i18n-formatter-display-name
src/formatting/date/	@suaveplan/i18n-formatter-date
src/formatting/currency/	@suaveplan/i18n-formatter-currency
src/formatting/index.ts	(deleted; root barrel re-exports per-formatter)
src/detector/ (entire directory)	@suaveplan/i18n-detector
src/core/backend/ (entire directory)	@suaveplan/i18n-backend-*

Files that stay in packages/i18n/i18n/src/:

Path	Role
src/core/catalog/	MessageCatalog, deepMerge — stays as the integration layer
src/core/plugin/	createI18n, I18nInstance — stays as the public top-level API
src/locale/negotiation/	negotiateLocale, parseAcceptLanguage — RFC 4647 lookup, foundational locale primitives
src/locale/resolver/	LocaleResolver, extractLanguage, extractRegion, normalizeLocaleCode — strategy-based resolver
src/middleware/	createLocaleMiddleware, detectLocale, getDirection server middleware
src/observability/	detector-metrics state, OTel adapters
src/schemas/	CatalogOptionsSchema, InterpolationConfigSchema, ResolverConfigSchema, TranslationRecordSchema — boundary validation
src/utils/	buildKey, countKeys, flattenRecord, getNestedValue, getTextDirection, hasKey, isRtl, parseKey, sanitize, unflattenRecord — key/translation utilities
src/conformance.test.ts	end-to-end spec conformance — REGRESSION GATE
src/index.ts	rewritten root barrel (back-compat)
src/index.test.ts	exhaustive symbol-existence test

Subpath exports preserved

Every existing package.json exports subpath continues to resolve. Internally the subpath forwards to the relevant new package. Documented subpaths:

• @suaveplan/i18n — root barrel
• @suaveplan/i18n/detector — forwards to @suaveplan/i18n-detector
• @suaveplan/i18n/plugin — forwards to local core/plugin/instance.ts
• @suaveplan/i18n/parser — forwards to @suaveplan/i18n-icu-parser/parser
• @suaveplan/i18n/errors — forwards to @suaveplan/i18n-shared/errors

Back-compat re-export map (exhaustive)

Every export in the current src/index.ts (211 lines, 33 export statements). Each row says: pre-split source → new source.

Symbol	Pre-split source	Post-split source
DefaultLocale (type)	./constants/index.js	@suaveplan/i18n-shared/constants/locale-descriptors
DEFAULT_INTERPOLATION	./constants/index.js	@suaveplan/i18n-shared/constants/interpolation-defaults
DEFAULT_LOCALES	./constants/index.js	@suaveplan/i18n-shared/constants/locale-descriptors
LOCALE_BCP47_MAP	./constants/index.js	@suaveplan/i18n-shared/constants/locale-bcp47-map
LOCALE_DESCRIPTORS	./constants/index.js	@suaveplan/i18n-shared/constants/locale-descriptors
RTL_LOCALE_LIST	./constants/index.js	@suaveplan/i18n-shared/constants/rtl-locales
RTL_LOCALES	./constants/index.js	@suaveplan/i18n-shared/constants/rtl-locales
deepMerge, MessageCatalog	./core/catalog/catalog.js	(stays — local)
CatalogOptions, ExtendedCatalogOptions (types)	./core/catalog/catalog.types.js	(stays — local)
LookupResult, MessageLoader, MissingKeyHandler, NamespacedCatalogMap, TranslationCatalogMap, TranslationRecord (types)	./core/catalog/catalog.types.js	@suaveplan/types (Wave 1a)
escapeHtmlChars, escapeRegex, InterpolationEngine	./core/interpolation/interpolation.js	@suaveplan/i18n-icu-parser/interpolation
InterpolationConfig, InterpolationOptions, InterpolationResult, InterpolationValues, ValueFormatter (types)	./core/interpolation/interpolation.types.js	@suaveplan/i18n-icu-parser/interpolation
I18nInstanceOptions (type)	./core/plugin/instance.js	(stays — local)
createI18n, I18nInstance	./core/plugin/instance.js	(stays — local; modified to wire default FormatBridge)
arabicPlural, chinesePlural, defaultPluralRule, englishPlural, frenchPlural, germanPlural, getBaseLocale, normalizeLocale, PluralizationEngine, polishPlural, russianPlural, spanishPlural, welshPlural	./core/pluralization/pluralization.js	@suaveplan/i18n-icu-parser/pluralization
PluralCategory, PluralMessages, PluralResolveOptions, PluralResolveResult, PluralRuleFunction, PluralRuleRegistry (types)	./core/pluralization/pluralization.types.js	@suaveplan/i18n-icu-parser/pluralization
DetectorChain, DetectorChainResult, DetectorChainUnresolved, DetectorContext, DetectorEnvironment, DetectorStorageLike, LocaleDetector (types)	./detector/index.js	@suaveplan/i18n-detector
createDetectorChain, DETECTOR_CHAIN_UNRESOLVED	./detector/index.js	@suaveplan/i18n-detector
I18nCode (type)	./error-codes.js	@suaveplan/i18n-shared/errors (renamed: I18nErrorCode is the new name; I18nCode is re-exported as a type alias for back-compat)
I18N_CODES	./error-codes.js	@suaveplan/i18n-shared/errors
I18nError	./errors/i18n-error.js	@suaveplan/i18n-shared/errors
formatCurrency, formatCurrencyValue, getCurrencyInfo, getCurrencyName, getCurrencySymbol	./formatting/currency/currency.js	@suaveplan/i18n-formatter-currency
CommonCurrency, CurrencyFormatOptions, CurrencyInfo (types)	./formatting/currency/currency.types.js	@suaveplan/i18n-formatter-currency
formatDate, formatDateOnly, formatDateRange, formatTime, getDayNames, getMonthNames	./formatting/date/date.js	@suaveplan/i18n-formatter-date
DateFormatOptions, DateFormatPreset, ExtendedDateOptions (types)	./formatting/date/date.types.js	@suaveplan/i18n-formatter-date
negotiateLocale, parseAcceptLanguage	./locale/negotiation/negotiation.js	(stays — local)
AcceptLanguageEntry, NegotiationOptions, NegotiationResult (types)	./locale/negotiation/negotiation.types.js	(stays — local)
extractLanguage, extractRegion, LocaleResolver, normalizeLocaleCode	./locale/resolver/resolver.js	(stays — local)
ExtendedResolverConfig, ResolutionStrategy, ResolvedLocale, ResolverConfig (types)	./locale/resolver/resolver.types.js	(stays — local)
createLocaleMiddleware, detectLocale, getDirection	./middleware/server/server.js	(stays — local)
ExtendedMiddlewareConfig, I18nRequest, LocaleLookupSource, MiddlewareConfig, MiddlewareResult, TextDirection (types)	./middleware/server/server.types.js	(stays — local)
DetectorMetricSample, DetectorMetricsState (types)	./observability/detector-metrics.js	(stays — local)
getDetectorMetrics, getDetectorMetricsState, recordDetectorDuration, recordDetectorMatch, resetDetectorMetricsCache, resetDetectorMetricsState	./observability/detector-metrics.js	(stays — local)
extractVariables, MessageParser, renderNodes	./parser/message/message.js	@suaveplan/i18n-icu-parser/parser
MessageNode, ParsedMessage, ParserOptions, PluralNode, SelectNode, TextNode, VariableNode (types)	./parser/message/message.types.js	@suaveplan/i18n-icu-parser/parser
CatalogOptionsInput, InterpolationConfigInput, ResolverConfigInput (types)	./schemas/i18n.schemas.js	(stays — local)
CatalogOptionsSchema, InterpolationConfigSchema, ResolverConfigSchema, TranslationRecordSchema	./schemas/i18n.schemas.js	(stays — local)
buildKey, countKeys, flattenRecord, getNestedValue, getTextDirection, hasKey, isRtl, parseKey, sanitize, unflattenRecord	./utils/utils.js	(stays — local)
KeyPathResult, SanitizeOptions (types)	./utils/utils.types.js	(stays — local)

Backend factories (MemoryBackend, memoryBackend, HttpBackend, httpBackend, StorageBackend, storageBackend, ChainedBackend, chainedBackend) are added to the root barrel even though they are not in the current 211-line index.ts — they were exported via the ./core/backend/* subpaths, and the slim core re-exports them at the root for parity with formatters and detector. MultiFileFsBackend / multiFileFsBackend are NOT added to the universal-tier root because the package is server-tier; consumers must import directly from @suaveplan/i18n-backend-fs-multifile.

Out of scope

• Migrating downstream consumers (@suaveplan/react-i18n, react-ui, react-forms) to direct per-package imports for tree-shaking — follow-up change. They keep working through the slim root barrel.
• Removing the ./detector / ./plugin / ./parser / ./errors subpaths from package.json exports — kept indefinitely for back-compat.
• Renaming I18nCode → I18nErrorCode as a breaking change — the new name is exported from @suaveplan/i18n-shared; the old name is kept as a type alias.
• Splitting locale/ into its own i18n-locale-resolver package — possible future change; out of scope here.
• Splitting middleware/server/ into a separate i18n-middleware package — possible future change; out of scope here.

Source mapping

This change is mostly deletion and re-export. The "source" for the back-compat barrel is the existing packages/i18n/i18n/src/index.ts (lines 1–211). For the bridge wiring:

Requirement	Source file	Source lines	Notes
Default FormatBridge wiring	packages/i18n/i18n/src/parser/message/message-render.ts	full file	Today's direct formatter calls become formatBridge.<name>(...) calls in Wave 2's i18n-icu-parser. The default bridge constructed in Wave 6 calls back into the current monolith's formatter functions (post-move: now in formatter packages).
Catalog FormatBridge plumbing	packages/i18n/i18n/src/core/catalog/catalog.ts	every renderNodes(...) call site	Add formatBridge to RenderOptions
Plugin FormatBridge plumbing	packages/i18n/i18n/src/core/plugin/instance.ts	every renderNodes(...) call site	Same

Requirements with no source line

Requirement	Justification
Slim-core root barrel	New shape; the export symbols match the existing barrel byte-for-byte but the sources change
Default FormatBridge factory in parser/format-bridge-default.ts	New file — needed because formatter packages now live outside the parser package
Backend re-exports in root barrel	New symbols at root; previously only accessible via ./core/backend/* subpaths. Adding them at root improves discoverability and matches formatter parity

Verification approach

This is the highest-risk change in the entire split. Verification is layered:

1. packages/i18n/i18n/src/conformance.test.ts — every existing test must remain green. This file tests the public surface end-to-end against real values; it is the strongest regression gate.
2. packages/i18n/i18n/src/index.test.ts — exhaustive symbol-existence test. Every one of the 33 exports + every backend re-export must resolve. Test enumerates the symbol list; failure means the back-compat barrel missed a symbol.
3. packages/react/react-i18n/ test suite — unchanged code, must remain green. 17 distinct import paths from @suaveplan/i18n (root + 4 subpaths) cover the most heavily-used downstream surface.
4. packages/react/react-ui/ test suite — must remain green.
5. packages/react/react-forms/ test suite — must remain green.
6. Per-package coverage — bunx turbo test:coverage --filter=@suaveplan/i18n must hit 100/100/100/100 on the slim core (the moved-out modules are no longer counted; the slim core's coverage focuses on catalog, plugin, locale, middleware, observability, schemas, utils, and the new bridge wiring).
7. Subpath resolution — a test that imports from each documented subpath (@suaveplan/i18n/detector, @suaveplan/i18n/plugin, @suaveplan/i18n/parser, @suaveplan/i18n/errors) and asserts the expected symbols resolve.
8. Bundle-size sanity — record the slim core's bundle size before and after. Expect a meaningful reduction (formatters / parser / backends were a large fraction of the monolith); document the new size in the README.

Impact

• @suaveplan/i18n shrinks from ~121 source files to ~25 (catalog + plugin + locale + middleware + observability + utils + schemas + conformance + bridge + barrel + tests).
• @suaveplan/i18n gains 15 new workspace:^ deps (Waves 1–5 packages).
• @suaveplan/i18n adds backend factories to its root barrel (4 universal-tier backends).
• Every existing import { X } from "@suaveplan/i18n" continues to work — zero downstream breakage expected.
• MANIFEST.md regenerated; CLAUDE.md listing for @suaveplan/i18n updated to reflect slim scope.
• All 14 OpenSpec change folders for the modular split (i18n-types-extension, i18n-shared, i18n-icu-parser, 8 formatters, i18n-detector, 5 backends, this folder) archive together to openspec/archive/2026-05-05-i18n-modular-split-*/.
• The cross-cutting design doc at openspec/cross-cutting-designs/2026-05-05-i18n-modular-split.md moves to the archive folder for the design (kept as a single design doc for the entire split, archived once on Wave 6 completion).
• This wave is the only crash-unsafe step in the entire split. If a session dies between deleting source and rewriting the barrel, the working tree is in a broken state. Mitigation: each deletion in §"Files DELETED" is its own commit (sub-commit within Wave 6); the barrel rewrite happens first, so even at the worst crash point the package still builds (it just has duplicate definitions until the deletes finish).