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

# `@suaveplan/i18n-detector` — locale detection chain

**Package**: `@suaveplan/i18n-detector` (NEW)
**Status**: PROPOSED
**Type**: feature (new universal-tier package; consolidates the misplaced react-i18n detector folder + the genesis monolith chain orchestrator)
**Date**: 2026-05-05
**Wave**: 4 (depends on Waves 1–2 foundation; required by Wave 6 core slim)
**Design doc**: `openspec/cross-cutting-designs/2026-05-05-i18n-modular-split.md`
**Tier**: universal
**Path**: `packages/i18n/i18n-detector/`

## Why

Locale detection is the single most architecturally mis-placed piece of the i18n stack on genesis today. The chain orchestrator (`createDetectorChain`, `DETECTOR_CHAIN_UNRESOLVED`, `LocaleDetector` interface, `DetectorContext`, `DetectorEnvironment`) lives in `packages/i18n/i18n/src/detector/` inside the universal-tier monolith. The eight individual detector implementations (querystring, user-preference, cookie, localStorage, html-lang, Accept-Language, navigator, Cloudflare IP-geo) plus a `defaultDetectorChain` factory and a `fallbackDetector` were authored under `packages/react/react-i18n/src/detector/` — a browser-tier React binding package — even though every detector is framework-agnostic and most have no DOM dependency at all (Accept-Language and IP-geo are server-only; querystring works on either side; only localStorage / html-lang / navigator actually touch a browser global, and even then only via a guarded `globalThis` probe).

The damage today:

1. **Tier inversion.** Server-only detectors (`acceptLanguageDetector`, `cloudflareIpGeoDetector`) live under a React binding package. A Node-only consumer that wants Accept-Language negotiation has to install React.
2. **Universal consumers can't compose chains.** Only React consumers see the eight detectors. A Hono / Express / Bun.serve handler that wants `cookieDetector + acceptLanguageDetector` has nothing to import.
3. **The chain orchestrator and its detectors are split across two packages.** `createDetectorChain` lives in `@suaveplan/i18n` but the only detectors that compose into it live in `@suaveplan/react-i18n`. `defaultDetectorChain` cannot live in a universal package without a React detour — the design doc explicitly flags this as the reason `i18n-detector` exists as a Wave 4 package.
4. **`getTextDirection` is misfiled.** Today it lives in `@suaveplan/i18n/utils/utils.ts` (`L142-L146`). It is a pure function over `RTL_LOCALES`; semantically it belongs with the detection / locale-direction surface, not with key-path utilities.

This change consolidates every detector implementation, the chain orchestrator, the standalone `getTextDirection` helper, and the `defaultDetectorChain` factory into a single universal-tier package: `@suaveplan/i18n-detector`. The package depends only on `@suaveplan/i18n-shared` (for `RTL_LOCALES`, `LOCALE_BCP47_MAP`, `I18N_CODES`, `I18nError`) and `@suaveplan/locale-data` (for the ISO 3166 `getAllCountries()` lookup the Cloudflare detector uses to map country codes to locales). It depends on neither `@suaveplan/i18n` core nor any formatter / backend / parser package.

### Dual-tier strategy (universal package, browser + server detectors)

The detector chain runs in both browser and server contexts. Universal-tier means every detector MUST gracefully short-circuit when the runtime it expects is absent. Concretely:

- **Browser-only detectors** (`htmlLangDetector`, `localStorageDetector`, `navigatorDetector`) probe `globalThis.document` / `globalThis.localStorage` / `globalThis.navigator` and return `null` when the global is absent. The chain orchestrator additionally honours `LocaleDetector.environment === "browser"` so server runs skip them entirely.
- **Server-only detectors** (`acceptLanguageDetector`, `cloudflareIpGeoDetector`) gate on `ctx.request !== undefined` and return `null` otherwise. Their `environment === "server"` causes the chain to skip them on a browser run.
- **Universal detectors** (`querystringDetector`, `cookieDetector`, `userPreferenceDetector`, `fallbackDetector`) carry `environment === "both"` and fall back through `ctx.request → globalThis` lookups so they work in either tier.

This is the same dual-tier pattern `@suaveplan/db-sqlite` uses (Bun on server / sqlite-wasm in browser): one universal package, runtime-checked branches per environment. No conditional `package.json` exports, no `node:` import in any source file.

## What changes

### New package: `@suaveplan/i18n-detector`

#### Types and chain orchestrator

- ADDED: `packages/i18n/i18n-detector/` package scaffold (package.json, tsconfig.json, vite.config.ts, README.md).
- ADDED: `src/detector.types.ts` — ports `DetectorStorageLike`, `DetectorContext`, `DetectorEnvironment`, `LocaleDetector`, `DetectorChainResult` from the monolith verbatim. Source: `packages/i18n/i18n/src/detector/detector.types.ts` (full file).
- ADDED: `src/chain/chain.ts` — ports `createDetectorChain`, `DETECTOR_CHAIN_UNRESOLVED`, `DetectorChainUnresolved`, `DetectorChain` from the monolith. Source: `packages/i18n/i18n/src/detector/chain/chain.ts` (full file). **Modified**: replaces direct `LocaleResolver` import with an injectable `negotiate: (raw: string, supported: readonly string[], fallback: string) => string | null` parameter on `createDetectorChain(detectors, options?)`. The package ships a default BCP-47 negotiator (`bcp47Negotiate`) that consumes `LOCALE_BCP47_MAP` from `@suaveplan/i18n-shared`. Throws `I18nError(I18N.DETECTOR_CHAIN_EXHAUSTED)` when `ctx.supportedLocales` is empty AND the consumer opted into `throwOnExhausted: true` (back-compat default returns `DETECTOR_CHAIN_UNRESOLVED`).
- ADDED: `src/chain/bcp47-negotiate.ts` — default `negotiate()` implementation that normalises raw locale via `LOCALE_BCP47_MAP`, walks supported locales for an exact / language-subtag match, and returns `null` on miss (so the chain advances to the next detector instead of forcing the fallback prematurely).
- ADDED: `src/chain/index.ts` — explicit named re-exports.

#### Direction helper

- ADDED: `src/direction/direction.ts` — exports `getTextDirection(locale: string): "ltr" | "rtl"` and `isRtl(locale: string): boolean`. Source: `packages/i18n/i18n/src/utils/utils.ts` `L138-L153` (port + retype: removes the indirect `import type { TextDirection } from "../middleware/server/server.types.js"` and inlines `type TextDirection = "ltr" | "rtl"` here).
- ADDED: `src/direction/index.ts` — explicit named re-exports.

#### Individual detector implementations

Each detector lives in its own folder with `<name>.ts`, `<name>.types.ts` (when options exist), `index.ts` (explicit named re-exports), `<name>.test.ts`, and `<name>.md`:

- ADDED: `src/detectors/querystring/querystring.ts` — `querystringDetector(options?: QuerystringDetectorOptions): LocaleDetector`. `environment: "both"`. Reads `?lang=` from `ctx.request.url.searchParams` (server) or `globalThis.location.search` via `URLSearchParams` (browser). Source: `packages/react/react-i18n/src/detector/querystring/querystring.ts` (full file, 42 lines).
- ADDED: `src/detectors/user-preference/user-preference.ts` — `userPreferenceDetector(options: UserPreferenceDetectorOptions): LocaleDetector`. `environment: "both"`. Async GET on `options.endpoint` + best-effort POST on cache. Replaces the direct `ConsoleLogger` dependency with the `LoggerLike` from `@suaveplan/types` accepted via `options.logger?` (defaults to a no-op so the package keeps zero non-shared deps). Source: `packages/react/react-i18n/src/detector/user-preference/user-preference.ts` (full file, 105 lines).
- ADDED: `src/detectors/cookie/cookie.ts` — `cookieDetector(options?: CookieDetectorOptions): LocaleDetector`. `environment: "both"`. Reads inbound `Cookie` header / writes `Set-Cookie` on `ctx.responseHeaders` (server) or reads/writes `document.cookie` (browser). Source: `packages/react/react-i18n/src/detector/cookie/cookie.ts` (full file, 110 lines).
- ADDED: `src/detectors/local-storage/local-storage.ts` — `localStorageDetector(options?: LocalStorageDetectorOptions): LocaleDetector`. `environment: "browser"`. Reads/writes `globalThis.localStorage` with `try/catch` for private-mode / quota failures. Source: `packages/react/react-i18n/src/detector/local-storage/local-storage.ts` (full file, 69 lines).
- ADDED: `src/detectors/html-lang/html-lang.ts` — `htmlLangDetector(): LocaleDetector`. `environment: "browser"`. Reads `document.documentElement.lang`. Source: `packages/react/react-i18n/src/detector/html-lang/html-lang.ts` (full file, 37 lines).
- ADDED: `src/detectors/accept-language/accept-language.ts` — `acceptLanguageDetector(): LocaleDetector` plus exported `parseAcceptLanguage(header: string): AcceptLanguageEntry[]`. `environment: "server"`. RFC 9110 §5.3.5 q-value parsing with stable sort. Source: `packages/react/react-i18n/src/detector/accept-language/accept-language.ts` (full file, 82 lines).
- ADDED: `src/detectors/navigator/navigator.ts` — `navigatorDetector(): LocaleDetector`. `environment: "browser"`. Reads `globalThis.navigator.languages` (preferred) or `navigator.language` (fallback). Source: `packages/react/react-i18n/src/detector/navigator/navigator.ts` (full file, 50 lines).
- ADDED: `src/detectors/cloudflare-ip-geo/cloudflare-ip-geo.ts` — `cloudflareIpGeoDetector(options?: CloudflareIpGeoDetectorOptions): LocaleDetector`. `environment: "server"`. Maps `cf-ipcountry` ISO 3166-1 alpha-2 to a BCP-47 locale via `getAllCountries()` from `@suaveplan/locale-data` plus an optional override map. Source: `packages/react/react-i18n/src/detector/cloudflare-ip-geo/cloudflare-ip-geo.ts` (full file, 50 lines).
- ADDED: `src/detectors/fallback/fallback.ts` — `fallbackDetector(locale: string): LocaleDetector`. `environment: "both"`. Always returns the configured locale. Throws `I18nError(I18N.INVALID_LOCALE)` on empty/whitespace input (replaces the upstream `throw new Error(...)`). Source: `packages/react/react-i18n/src/detector/fallback/fallback.ts` (full file, 24 lines).

#### Default chain factory

- ADDED: `src/default-chain/default-chain.ts` — `defaultDetectorChain(options: DefaultDetectorChainOptions): LocaleDetector[]` returning the canonical 8-or-9-entry chain (querystring → userPreference? → cookie → localStorage → htmlLang → acceptLanguage → navigator → cloudflareIpGeo → fallback). Source: `packages/react/react-i18n/src/detector/default-chain/default-chain.ts` (full file, 54 lines).

#### Root barrel

- ADDED: `src/index.ts` — explicit named re-exports of every public symbol across `chain/`, `direction/`, `detectors/`, and `default-chain/`. NO `export *` per CLAUDE.md §10.

### Subpath exports (per `package.json` `exports` map)

- `.` — root barrel (every public symbol)
- `./chain` — `createDetectorChain`, `DETECTOR_CHAIN_UNRESOLVED`, `DetectorChain`, `DetectorChainUnresolved`, `bcp47Negotiate`
- `./direction` — `getTextDirection`, `isRtl`
- `./detectors/querystring` — `querystringDetector`, `QuerystringDetectorOptions`
- `./detectors/user-preference` — `userPreferenceDetector`, `UserPreferenceDetectorOptions`, `UserPreferenceResponseBody`
- `./detectors/cookie` — `cookieDetector`, `CookieDetectorOptions`, `CookieSameSite`
- `./detectors/local-storage` — `localStorageDetector`, `LocalStorageDetectorOptions`, `LocalStorageLike`
- `./detectors/html-lang` — `htmlLangDetector`
- `./detectors/accept-language` — `acceptLanguageDetector`, `parseAcceptLanguage`, `AcceptLanguageEntry`
- `./detectors/navigator` — `navigatorDetector`
- `./detectors/cloudflare-ip-geo` — `cloudflareIpGeoDetector`, `CloudflareIpGeoDetectorOptions`
- `./detectors/fallback` — `fallbackDetector`
- `./default-chain` — `defaultDetectorChain`, `DefaultDetectorChainOptions`

### Dependencies

- `@suaveplan/i18n-shared workspace:^` — for `RTL_LOCALES` (direction), `LOCALE_BCP47_MAP` (BCP-47 normalisation in default negotiator), `I18N_CODES` + `I18nError` (every error throw).
- `@suaveplan/locale-data workspace:^` — for `getAllCountries()` consumed by `cloudflareIpGeoDetector` to map ISO 3166-1 alpha-2 → BCP-47.
- `@suaveplan/types workspace:^` — for `LoggerLike` shape consumed by `userPreferenceDetector`.
- `@suaveplan/error workspace:^` — for `defineCodes` consumer-side helpers (re-export consumers may need).
- `@opentelemetry/api catalog:observability` — for chain + per-detector histograms / counters.
- `tslib catalog:build` — TS helper inlining.
- `zod catalog:forms` — boundary schemas (`DetectorContextSchema`, `DefaultDetectorChainOptionsSchema`, every `<Detector>OptionsSchema`).

### Observability

- `i18n.detector.<name>.duration_ms` (histogram) — per detector, async-detector wall time.
- `i18n.detector.<name>.detected_total{locale=<resolved>}` (counter) — per detector, increments on a non-null resolution.
- `i18n.detector.chain.exhausted_total` (counter) — increments every time the entire chain returns `DETECTOR_CHAIN_UNRESOLVED`.
- `i18n.detect` (span) — wraps every chain run; sets `resolved_locale` and `winning_detector` attributes (already present in monolith chain).

### AbortSignal contract

Every async detector (`userPreferenceDetector.detectAsync`, `userPreferenceDetector.cache`, `cloudflareIpGeoDetector.detect` if extended in future) MUST honour `ctx.signal` by passing it on `RequestInit.signal`. The chain orchestrator threads `ctx.signal` through unchanged. A pre-aborted signal returns `null` from the detector immediately (caught + logged at warn via the injected `logger`).

## Out of scope

- **Removing the detector folder from `packages/i18n/i18n/src/`** — happens in Wave 6 (`i18n-core-slim`). For Waves 4–5 the monolith retains its copy and the leaves consume from `@suaveplan/i18n-shared` + this package; both compile.
- **Removing the detector folder from `packages/react/react-i18n/src/`** — that follow-up change re-exports every symbol from this package and is tracked separately as `react-i18n-detector-reexport`.
- **Adding new detectors beyond the existing 8** — the design doc lists exactly the eight currently in the react-i18n source. New detectors (Vercel `x-vercel-ip-country`, Fastly `Fastly-Geo-Country`, custom-header) ship in follow-ups, each as its own subpath under `./detectors/<name>/`.
- **Replacing the chain's `LocaleResolver` dependency with a full-featured negotiator (CLDR fallback chain, script-aware matching, RFC 4647 lookup)** — the embedded `bcp47Negotiate` covers the existing monolith's `LocaleResolver.resolve()` happy path; full CLDR support is a follow-up that lands as `i18n-shared-cldr-negotiate`.
- **Persisting cookie SameSite=None requires Secure flag enforcement** — the current implementation does not auto-add `; Secure` for `SameSite=None`; that is tracked as `cookie-detector-secure-flag` (separate change).

## Source mapping

| Requirement | Source file | Source lines | Notes |
|---|---|---|---|
| `LocaleDetector`, `DetectorContext`, `DetectorEnvironment`, `DetectorChainResult`, `DetectorStorageLike` types | `packages/i18n/i18n/src/detector/detector.types.ts` | L1-L87 | Verbatim port |
| `createDetectorChain`, `DETECTOR_CHAIN_UNRESOLVED`, `DetectorChain`, `DetectorChainUnresolved` | `packages/i18n/i18n/src/detector/chain/chain.ts` | L1-L220 | Port; replace `LocaleResolver` import with injectable `negotiate` parameter |
| `getTextDirection`, `isRtl` | `packages/i18n/i18n/src/utils/utils.ts` | L138-L153 | Port; inline `type TextDirection = "ltr" \| "rtl"` (drop `middleware/server/server.types` import) |
| `querystringDetector`, `QuerystringDetectorOptions` | `packages/react/react-i18n/src/detector/querystring/querystring.ts` | L1-L42 | Verbatim port; rewire `LocaleDetector` import to `../../detector.types.js` |
| `userPreferenceDetector`, `UserPreferenceDetectorOptions`, `UserPreferenceResponseBody` | `packages/react/react-i18n/src/detector/user-preference/user-preference.ts` | L1-L105 | Port; replace `ConsoleLogger` dep with `options.logger?: LoggerLike` |
| `cookieDetector`, `CookieDetectorOptions`, `CookieSameSite` | `packages/react/react-i18n/src/detector/cookie/cookie.ts` | L1-L110 | Verbatim port |
| `localStorageDetector`, `LocalStorageDetectorOptions`, `LocalStorageLike` | `packages/react/react-i18n/src/detector/local-storage/local-storage.ts` | L1-L69 | Verbatim port |
| `htmlLangDetector` | `packages/react/react-i18n/src/detector/html-lang/html-lang.ts` | L1-L37 | Verbatim port |
| `acceptLanguageDetector`, `parseAcceptLanguage`, `AcceptLanguageEntry` | `packages/react/react-i18n/src/detector/accept-language/accept-language.ts` | L1-L82 | Verbatim port |
| `navigatorDetector` | `packages/react/react-i18n/src/detector/navigator/navigator.ts` | L1-L50 | Verbatim port |
| `cloudflareIpGeoDetector`, `CloudflareIpGeoDetectorOptions` | `packages/react/react-i18n/src/detector/cloudflare-ip-geo/cloudflare-ip-geo.ts` | L1-L50 | Verbatim port; `getAllCountries` import already targets `@suaveplan/locale-data` |
| `fallbackDetector` | `packages/react/react-i18n/src/detector/fallback/fallback.ts` | L1-L24 | Port; replace `throw new Error(...)` with `throw new I18nError(I18N_CODES.INVALID_LOCALE, ...)` |
| `defaultDetectorChain`, `DefaultDetectorChainOptions` | `packages/react/react-i18n/src/detector/default-chain/default-chain.ts` | L1-L54 | Verbatim port; rewire detector imports to sibling folders |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `bcp47Negotiate` default negotiator | Today the chain hard-imports `LocaleResolver` from `../../locale/resolver/resolver.js`. The detector package cannot pull the resolver without dragging the entire schemas / errors / locale subtree with it; the cleanest split is a small embedded negotiator that handles the monolith's happy-path negotiation against `LOCALE_BCP47_MAP` and accepts an injectable `negotiate` for advanced consumers (slim core wires the full `LocaleResolver` in Wave 6) |
| Subpath exports per individual detector | Tree-shaking — a Hono server consumer should be able to import only `@suaveplan/i18n-detector/detectors/accept-language` without pulling browser-only detectors |
| OTel histograms `i18n.detector.<name>.duration_ms` and counters `i18n.detector.<name>.detected_total` | Today the monolith chain emits aggregated `i18n.detector.match_total{detector}` and `i18n.detector.duration_ms{detector}`. Per-package split keeps the same surface but moves the metrics to per-detector helpers so the chain orchestrator stays decoupled from any specific detector implementation |
| `i18n.detector.chain.exhausted_total` counter | New observability surface — the monolith silently returns the unresolved sentinel; production needs a counter to alert on chain exhaustion |
| `I18nError(I18N.DETECTOR_CHAIN_EXHAUSTED)` thrown when `throwOnExhausted: true` | New error path — the monolith only returns the sentinel; production consumers (especially server-side renderers) need a typed throw they can catch and map to a 4xx |

## Verification approach

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

- `packages/i18n/i18n-detector/src/chain/chain.test.ts` — sync chain runs in registration order, async chain races, environment gating, `DETECTOR_CHAIN_UNRESOLVED` sentinel, `cache()` walks every persisting detector, AbortSignal threading, throw-on-exhausted opt-in
- `packages/i18n/i18n-detector/src/chain/bcp47-negotiate.test.ts` — exact match, language-subtag fallback (`zh-Hant-TW` → `zh`), `null` on miss, `LOCALE_BCP47_MAP` short-code expansion (`en` → `en-GB`)
- `packages/i18n/i18n-detector/src/direction/direction.test.ts` — `getTextDirection("ar")` is `"rtl"`, `getTextDirection("en-GB")` is `"ltr"`, language-subtag extraction works (`ar-SA` → `"rtl"`); `isRtl` mirrors
- `packages/i18n/i18n-detector/src/detectors/querystring/querystring.test.ts` — server `?lang=fr` resolves; browser `globalThis.location.search` resolves; missing param returns `null`; both contexts absent returns `null`
- `packages/i18n/i18n-detector/src/detectors/user-preference/user-preference.test.ts` — happy GET returns body locale; non-2xx logs + returns `null`; rejected fetch returns `null`; AbortSignal threaded; cache POST round-trips; cache failure is non-fatal
- `packages/i18n/i18n-detector/src/detectors/cookie/cookie.test.ts` — server reads inbound Cookie header; server writes Set-Cookie on responseHeaders; browser reads/writes `document.cookie`; URL-encoding round-trip; SameSite formatting
- `packages/i18n/i18n-detector/src/detectors/local-storage/local-storage.test.ts` — explicit storage option; `globalThis.localStorage` fallback; missing storage returns `null`; quota error caught
- `packages/i18n/i18n-detector/src/detectors/html-lang/html-lang.test.ts` — `ctx.document` lookup; `globalThis.document` fallback; missing root returns `null`; empty `lang` returns `null`
- `packages/i18n/i18n-detector/src/detectors/accept-language/accept-language.test.ts` — q-value sort; stable order on ties; `*` wildcard skipped; malformed q skipped; missing header returns `null`
- `packages/i18n/i18n-detector/src/detectors/navigator/navigator.test.ts` — `navigator.languages` preferred; `navigator.language` fallback; missing navigator returns `null`
- `packages/i18n/i18n-detector/src/detectors/cloudflare-ip-geo/cloudflare-ip-geo.test.ts` — `AE` → `ar-AE` via locale-data; override map wins; missing header returns `null`; unknown country returns `null`
- `packages/i18n/i18n-detector/src/detectors/fallback/fallback.test.ts` — returns configured locale; empty locale throws `I18nError(I18N.INVALID_LOCALE)`
- `packages/i18n/i18n-detector/src/default-chain/default-chain.test.ts` — order matches spec; `userPreference` only when endpoint set; result is a fresh array; fallback always last
- `packages/i18n/i18n-detector/src/index.test.ts` — every documented subpath export resolves

## Impact

- New universal-tier package — joins `@suaveplan/i18n-shared`, `@suaveplan/i18n-icu-parser`, and `@suaveplan/locale-data` under `packages/i18n/`.
- `@suaveplan/i18n` slim core (Wave 6) re-exports `createDetectorChain`, `getTextDirection`, `LocaleDetector`, `DetectorContext` from this package — every existing consumer keeps working.
- `@suaveplan/react-i18n` (follow-up `react-i18n-detector-reexport` change) deletes its own `src/detector/` folder and re-exports the eight detectors plus `defaultDetectorChain` from this package.
- `MANIFEST.md` regenerated via `bun scripts/folder-reorg/generate-manifest.ts`.
- `CLAUDE.md` package listing updated with a one-line entry under the i18n cluster.
- Net dependency-graph effect: removes `@suaveplan/i18n` ← `@suaveplan/react-i18n` runtime coupling for detector composition (was only resolved via the `@suaveplan/i18n/detector` subpath today).