i18n infrastructure (SPA foundation): react-i18next + resolution + string sweep (tracker) #182

Split from #45. This is the SPA i18n FOUNDATION; the API half is #45 and lands first (this needs GET /me for language and the errorCodes extension to translate validation errors). Ships English-only; first pack (Spanish) is Phase 1.5 (epic #15).

Part of epic #14 (Phase 1.1). Spec: §4.5, §5.2, §24, UC-012.

Plan hardened after a codex (repo-aware) + pi review. Corrections marked ⓡ.

📊 Status (updated 2026-07-28)

✅ SWEEP COMPLETE. All batches B0–B6b shipped (#252 merged 2026-07-28) + the login/refresh language memory fix (#253 merged). The ONLY remaining work is the native-speaker es/tl review (human translation reconciliation, not code) — this tracker stays open for it.

Foundation: shipped (#233 merged) + es/tl subset packs (#234 merged). Full string sweep: COMPLETE (#252 merged). Hardcoded-string count on src/routes+src/components: 843 → 3 (the 3 are scanner false positives — code fragments, not strings). Every client-authored SPA string is in the catalog; the only intentional survivor is index.html's <title>Cluckwork</title> (brand).

Key decision — translate-now (revised 2026-07-28). The sweep began English-first (externalize English now, defer es/tl to one native pass), but partway through we switched: every swept screen now ships machine-drafted es/tl inline, marked // machine-drafted (#182) — pending native review, and is added to TRANSLATED_NAMESPACES. So Spanish/Tagalog mode renders translated across the app now; the scheduled native-speaker review still reconciles word choices (this issue stays open for it). Rationale for the switch: the English-first fallback left most screens showing English in Spanish mode, which read as broken.

Coverage: all 29 namespaces translated (en + machine-drafted es/tl, pending native review) — the already-translated set + enums (incl. auditAction/entityType) + B4 + B5 (#248) + the B1–B3 catch-up (#249) + help prose (#251) + help glossary (#252). Spanish/Tagalog mode renders translated across the entire app.

Sweep plan: docs/superpowers/plans/2026-07-27-i18n-string-sweep.md (reviewed by 5 lenses pre-execution; findings folded).

Batch tracker

• B0 — sweep foundation (PR F182 B0: i18n sweep foundation — English-first parity, typed enums, html-lang, pilot retrofit #237, merged): English-first parity allowlist + shape/non-empty guards; typed enums module (11 closed-vocabulary families, flat keys, exhaustive-union helpers → compile-time drift, raw fallback); <html lang> sync; complete common atoms; SalesPage pilot retrofit; npm run i18n:scan detector + CONTRIBUTING update.
• B1 — shared chrome + primitives (PR F182 B1: i18n sweep — shared chrome + primitives (nav labelKey, AppLayout, dialogs, PWA) #238, merged): nav (typed labelKey), AppLayout (+ skip-link & catalog document.title), BottomNav, Dialog, NumberField, ErrorBoundary, ThemeToggle, useConfirm, PWA UpdatePrompt. Scan 843→827.
• B2 — daily ops (PR F182 B2: i18n sweep — daily ops (DailyEntry, Dashboard, Water, Grades) — stacked on #238 #239, merged): DailyEntryPage · Dashboard · WaterPage · GradesPage. ManagerAdjusted → "Adjusted" harmonization. Scan →707.
• B3 — inventory (PR F182 B3: i18n sweep — inventory domain (Inventory, Products, Stock, Flocks) — stacked on #239 #240, merged): InventoryPage · ProductsPage · StockPage · FlocksPage. Fully behavior-preserving (all enum labels identity). Scan →531.
• B4 — finance & people (PR F182 B4: i18n sweep — finance & people (Settings, Users, Expenses, Customers, Account) #241, merged): SettingsPage · UsersPage (role enum; ReadOnly→"Read-only") · ExpensesPage (no method enum — category is data) · CustomersPage · remainder of AccountPage. Scan →398. es/tl backfilled for this batch (mid-batch decision): settings/users/expenses/customers + shared enums machine-drafted into es/tl and added to TRANSLATED_NAMESPACES (pending native review) — so Spanish/Tagalog mode renders translated on these screens. Enum chips now translate app-wide (bonus). B1–B3 remain English-first (es/tl still deferred to the native pass).
• B5 — records & export (PR F182 B5: i18n sweep — records & export (History, Reports, Audit, Export) #248, merged — es/tl included): HistoryPage · ReportsPage (+ NEW render tests — was 0% covered; coverage rose) · AuditPage · ExportPage. auditAction (28) + entityType (13) enum displays authored here as typed families (deferred from B0) — friendly-labelled + translated es/tl. Scan →329. Surfaced a pre-existing audit-filter drift (server 31 codes vs client 28) → filed Audit log: action filter + entityType labels drift from server (3 actions + FarmLogo missing) #247 (not a B5 regression).
• B1–B3 es/tl catch-up (PR F182 i18n: es/tl catch-up for B1–B3 screens (nav, daily ops, inventory) #249, merged): machine-drafted es/tl for the 14 B1–B3 screen namespaces (nav/primitives, daily ops, inventory) under the translate-now switch. Catalog-only; parity green; brought TRANSLATED_NAMESPACES to 24.
• B6a — Help page prose (PR F182 B6a: i18n sweep — Help page prose (translated inline) #251, merged): the in-app guide's prose → help ns (150 keys, 74 <Trans> sites), translated inline. Scan →81.
• B6b — Help glossary + final sweep audit (PR F182 B6b: i18n sweep — Help glossary + final sweep audit (sweep complete) #252, merged): the 37-row Glossary table → help ns (76 keys) + the catalog-wide audit (scan clean, stale English-first comments corrected, GLOSSARY pass, coverage/build). Scan →3 (false positives). Sweep code-complete: all client-authored SPA copy externalized + machine-drafted es/tl app-wide.
• Login/refresh language memory (PR fix(web): remember last UI language on this device (login screen + F5 no longer revert to English) (#182) #253, merged): device-local cluckwork.lang hint seeds i18next at module load so the pre-auth login screen AND a signed-in F5 open in the last-used language instead of flashing back to English — realizes the optional "persisted non-sensitive local language hint" noted in the technical approach. /me stays authoritative and self-heals the hint. +regression guard bootSeed.test.ts (mutation-probed).

Stays open after the English sweep for

• Native-speaker review of es/tl for all swept screens (the deferred translation pass).
• Reconcile the temporary sales:status* duplicate into a then-translated shared enums:status. ✅ PR refactor(web): reconcile sales:status* duplicate onto shared enums:status (#182) #254, merged 2026-07-28: SalesPage's filter dropdown + voided-payment badge render via statusLabel(); the 4 sales:status* keys deleted from en/es/tl (values byte-identical to enums:status, so behavior-preserving); wiring test added; reviewed codex + 2 Claude agents + pi (unanimous approve).
• Optional: consolidate pwa.reload/errorBoundary.reload into a shared common.reload atom if a third site appears.

Scope boundary: "all client-authored SPA copy" excludes server-authored text — uncoded validation messages render ApiError.message = server English by design; coded errors already map via errorCodes (#45).

Goal

The i18n plumbing in the SPA, so new screens add catalog keys instead of hardcoded strings, and the stored §4.5 settings finally drive display. English is the source of truth and the fallback.

ⓡ Scope of "done." The spec requires all UI strings in the catalog (specs.md:710, :2128; Sprint E retrofit). Incremental PRs are fine; incremental completion is not. So this issue is the foundation (library + resolution + convention + a representative pilot), and it stays open as the tracker for the full string sweep, which blocks Phase 1.5 (no Spanish pack can ship against half-externalized screens). The sweep may be split into numbered migration issues when scheduled.

Decisions (inherited from #45)

• UI language (string catalog) ≠ farm locale (number/date/money formatting, §4.5, unchanged). A user reading Spanish on a en-US farm still sees $ and MM/DD/YYYY.
• Resolution order: users.language (if a pack exists) → farm-locale's language subtag → English. Stored-but-unsupported = unset, never an error.
• ⓡ Farm locale is available: GET /account already returns locale (AccountResponse.Locale) and the SPA Account type has it — the fallback has its source, no new API dependency.

Technical approach

• Library: react-i18next (+ i18next). Standard, ~11 kB gz, useTranslation/<Trans>, built-in missing-key fallback. (FormatJS heavier; hand-rolled rejected per the framework-over-handrolled rule.)
• English catalog as source of truth, namespaced by area (common, auth, dailyEntry, sales, …). ⓡ Typed keys via CustomTypeOptions module augmentation (types/i18next.d.ts, resources: typeof en) so t("missing") is a compile error — with the accepted burden of keeping the type in sync with the catalog.
• ⓡ t() vs <Trans> convention: t() for plain strings; <Trans> only for strings interleaving JSX. Documented in a CONTRIBUTING/DESIGN note so usage stays consistent across the sweep.
• ⓡ One coordinated authenticated bootstrap — not independent providers. After ProtectedRoute's silent-refresh gate, fetch /me and /account concurrently, resolve the language, initialise i18next with the resolved language (NOT at module load — initialising with a language before resolution causes an English→resolved flash), and only then expose the authenticated shell. A failed read settles to farm-locale/English fallback, never a permanent blank. Note the AuthContext hazard: it marks the user authenticated immediately on token receipt (AuthContext.tsx:84), so a provider reacting later in an effect could allow one English render — the bootstrap must gate BEFORE the shell renders.
• ⓡ "Before first paint" is qualified to the AUTHENTICATED shell. /login is outside ProtectedRoute and a logged-out browser has no /me, so public/login UI is unavoidably English (or, optionally, a persisted non-sensitive local language hint for returning users). This is the honest promise; do not claim login-screen language resolution.
• Validation errors: ⓡ parseError (api/client.ts) reads the API's errorCodes when present, maps each code to a catalog message, and falls back to the English errors message at the SAME array index when a code has no key or no code was emitted. Codes are explicit-only (i18n infrastructure (API half): validation error codes + users.language + GET/PATCH /me #45), so an uncoded field simply keeps its English message.

Scope (foundation) — shipped in #233

• react-i18next + i18next; typed English catalog (CustomTypeOptions); missing key → English (never blank or raw key)
• Coordinated bootstrap: concurrent /me + /account, resolution (§4.5), i18next init with resolved language, shell gated until ready, failure → fallback
• parseError reads errorCodes → catalog message, index-aligned English fallback
• Formatting stays farm-locale-driven regardless of UI language (guardrail + a test that mocks language and asserts money/date output is unchanged)
• Language selector wired to PUT /me/language, hidden while English-only
• Convention documented (t()/<Trans>, key naming, sentence casing; new screens add keys)
• Pilot: externalize login + one dense screen (daily entry or sales) as the worked pattern
• Vitest: catalog fallback, resolution chain + no-flash gating, a screen rendering from keys, parseError code→message mapping, formatting-independent-of-language, hidden-selector

Full string sweep (tracked here; blocks Phase 1.5) — see the Batch tracker above

ⓡ Not just route headings — includes shared components, navigation, status badges, accessibility labels, confirmation dialogs, client-side validation messages, error-boundary copy, and the Help page. Being externalized batch-by-batch (B0–B6 above); this issue stays open until the sweep AND the native-review es/tl pass are complete.

Out of scope

• Machine-drafting es/tl inline for swept screens — superseded by the translate-now switch (see Status): every swept screen now ships machine-drafted es/tl inline. The native-speaker review of those drafts remains the open pass; a reviewed pack is Phase 1.5, epic EPIC: Phase 1.5 — Egg product hardening #15.
• Per-farm language; locale/currency behaviour (§4.5 unchanged)
• The API half (i18n infrastructure (API half): validation error codes + users.language + GET/PATCH /me #45)

Sequencing

After #45. Foundation shipped (#233); string sweep in follow-up area PRs (B0–B6), tracked here.