suaveplan/openspec/archive/2026-05-09-i18n-formatter-segmenter/proposal.md

@suaveplan/i18n-formatter-segmenter — Intl.Segmenter wrapper (NEW formatter)

Package: @suaveplan/i18n-formatter-segmenter (NEW) Status: PROPOSED Type: feature (new universal-tier package — brand-new addition; no source in current monolith) Date: 2026-05-05 Wave: 3 (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 §5 formatter package shape, §7.1 — closes the "two new formatters" gap from the original i18n-formatters change scope) Path: packages/i18n/i18n-formatter-segmenter/ Tier: universal

Why

The original i18n-formatters change folder (now archived under openspec/archive/2026-05-04-i18n-formatters/) listed Collator and Segmenter in its scope but the implementation never landed — only the four headline formatters (number, relative-time, list, date) shipped in the monolith. This change closes the second half of that gap as part of Wave 3 of the modular split.

Intl.Segmenter is the canonical cross-runtime API for locale-aware text segmentation by grapheme, word, or sentence. Concrete uses across the monorepo:

• @suaveplan/security-codes today scans for sensitive substrings; word-boundary-aware redaction (e.g. masking only complete words) belongs on top of Intl.Segmenter.
• @suaveplan/react-rich-text (Wave 3c-bound, downstream) needs grapheme-aware cursor movement (single emoji = single grapheme even across multiple code units) — Intl.Segmenter("en-GB", { granularity: "grapheme" }) is the right primitive.
• @suaveplan/i18n-icu-parser plural-rule selection at glyph boundaries benefits from grapheme segmentation (today the parser counts code units, which is correct for digits but wrong for emoji-prefixed numbers in some experimental ICU extensions — out of scope for this package, in scope for a follow-up).

Building this formatter from scratch follows the same Wave-3 formatter shape as every sibling package (Zod-validated options, per-(locale, options-hash) cache, OTel histogram + cache-hit counter, structured error mapping, side-effect-free).

What changes

New package: @suaveplan/i18n-formatter-segmenter

• ADDED: packages/i18n/i18n-formatter-segmenter/ package scaffold (package.json, tsconfig.json, vite.config.ts, README.md).
• ADDED: src/formatter.ts — SegmenterFormatter class wrapping Intl.Segmenter with construction-time Zod option validation; segmentText(input, locale, options?) standalone (returns string[] of segments — analogue of formatList); formatSegments(input, locale, options?) standalone (returns Intl.SegmentData[] with full index / segment / isWordLike metadata for each segment); clearSegmenterCache test-only helper. Per-(locale, granularity) cache key ${locale}|${granularity}.
• ADDED: src/formatter.types.ts — SegmenterGranularity ("grapheme" | "word" | "sentence"), SegmenterFormatterOptions ({ readonly granularity?: SegmenterGranularity }), SegmentData (re-export of Intl.SegmentData with stable shape), SegmenterFormatterCacheKey.
• ADDED: src/formatter.schemas.ts — SegmenterFormatterOptionsSchema Zod schema validating granularity ∈ {grapheme, word, sentence}.
• ADDED: src/helpers.ts — countGraphemes(input, locale) (returns the grapheme count for emoji-aware character counting); splitWords(input, locale) returns the word-segments only (filters isWordLike: true); splitSentences(input, locale) returns sentence-granularity segments.
• ADDED: src/observability.ts — local OTel histogram i18n.format.segmenter.duration_ms + counter i18n.format.cache_hit{formatter="segmenter"}.
• ADDED: src/formatter.test.ts — covers grapheme / word / sentence granularity; emoji handled as single grapheme; class twins helper; Zod failure → INVALID_FORMATTER_OPTIONS; bogus locale → UNSUPPORTED_LOCALE.
• ADDED: src/formatter.spec-conformance.test.ts — every requirement scenario in this delta runs as an executable test.
• ADDED: src/helpers.test.ts — covers all three ergonomic helpers (especially countGraphemes on emoji input).
• ADDED: src/index.ts — explicit named re-exports.
• ADDED: src/formatter.md, src/helpers.md, src/observability.md — sibling docs.

Subpath exports

• . — root barrel
• ./formatter — SegmenterFormatter class + segmentText + formatSegments + types + schema only
• ./helpers — countGraphemes, splitWords, splitSentences only

Dependencies

• @suaveplan/i18n-shared workspace:^ — I18N_CODES, I18nError
• @suaveplan/types workspace:^
• @suaveplan/error workspace:^
• @opentelemetry/api catalog:observability
• tslib catalog:build
• zod catalog:forms
• No dep on any other formatter package, on @suaveplan/i18n core, or on any backend package.

Out of scope

• Custom segmentation rules (e.g. ICU tailoring rules) — out of scope; matches Intl.Segmenter capabilities only.
• Pre-Intl.Segmenter runtime polyfill — out of scope; Intl.Segmenter shipped in Node 16+, Bun, and every major browser. Older runtimes are not supported.
• SegmentIterator streaming over ReadableStream — out of scope; Intl.Segmenter.segment() accepts only a string. Streaming text segmentation is a follow-up (likely a separate @suaveplan/i18n-formatter-segmenter-stream package).
• Removing this from the monolith — N/A (the monolith never shipped a segmenter).

Source mapping

Requirement	Source file	Source lines	Notes
All requirements	(no source in monolith)	—	Brand-new package; designed from scratch using @suaveplan/i18n-formatter-number (packages/i18n/i18n/src/formatting/number/number.ts) as the shape template

Requirements with no source line

Requirement	Justification
SegmenterFormatter class wrapping Intl.Segmenter	Brand-new — closes the original i18n-formatters change scope; required by Wave 6 default FormatBridge for future grapheme-aware ICU extensions
segmentText, formatSegments standalones	Brand-new — segmentText returns string[] (most consumer-friendly for splitting); formatSegments returns SegmentData[] (preserves index and isWordLike metadata)
Per-(locale, granularity) cache	Mandatory per Wave-3 formatter shape — every other formatter in the family ships this; smaller cache key (only granularity) than NumberFormatter because Intl.Segmenter has only one option
Zod schema, INVALID_FORMATTER_OPTIONS, UNSUPPORTED_LOCALE mappings	Mandatory per Wave-3 formatter shape
OTel histogram i18n.format.segmenter.duration_ms + cache-hit counter i18n.format.cache_hit{formatter="segmenter"}	Mandatory per Wave-3 formatter shape
Three ergonomic helpers (countGraphemes, splitWords, splitSentences)	Symmetric with formatPercent / formatCompact / formatUnit for the number formatter; covers the highest-frequency real-world segmentation use cases

Verification approach

• packages/i18n/i18n-formatter-segmenter/src/formatter.test.ts — segmentText("hello world", "en-GB", { granularity: "word" }) returns ["hello", " ", "world"] (or platform-equivalent); grapheme granularity treats "👨‍👩‍👧" as a single segment; sentence granularity splits on ./?/!; class wrapper twins helper output; Zod failure → INVALID_FORMATTER_OPTIONS; bogus locale → UNSUPPORTED_LOCALE; cache reuse on identical key
• packages/i18n/i18n-formatter-segmenter/src/formatter.spec-conformance.test.ts — every requirement scenario runs as an executable test
• packages/i18n/i18n-formatter-segmenter/src/helpers.test.ts — countGraphemes("👨‍👩‍👧", "en-GB") returns 1; countGraphemes("hello", "en-GB") returns 5; splitWords("hello, world!", "en-GB") returns ["hello", "world"] (filters non-word-like segments); splitSentences("Hi. How are you?", "en-GB") returns two sentence segments
• packages/i18n/i18n-formatter-segmenter/src/observability.test.ts — histogram named i18n.format.segmenter.duration_ms; counter i18n.format.cache_hit{formatter="segmenter"} increments only on second call with same (locale, granularity)
• packages/i18n/i18n-formatter-segmenter/src/index.test.ts — every documented public export resolves; subpaths resolve

Impact

• New universal-tier package — joins the rest of the i18n family.
• Indirect consumer in Wave 6: @suaveplan/i18n slim core re-exports SegmenterFormatter and formatSegments under the back-compat root barrel (per design doc §8.1 — formatSegments is the listed re-export).
• Closes a gap from the original i18n-formatters change scope (now archived under openspec/archive/2026-05-04-i18n-formatters/).
• MANIFEST.md and CLAUDE.md updated post-merge.