Purged from docs/superpowers by the gitflow finish of step 1 (BDR-065); that path is purged at every finish, so the records live under docs/history/superpowers/ instead. References updated.
6.8 KiB
B3 — i18n FR/EN (site + PDF) — Design
Date: 2026-05-20
Branch: feat/findings-tree-v2
Status: Approved → implementation
Cross-refs: TODO.md Phase B B3; BDR-010 (snapshot labels at selection); BDR-009 (snake_case JSON fields preserved); LRN-012 (sessionStorage once-per-session modal)
1. Goal
Add bilingual French / English UI and PDF export to Osteo Report. Practitioner picks the locale; all interface strings and PDF static labels render in that locale. Finding leaf names render via the dual snapshot already stored on each Finding (labelFrSnapshot / labelEnSnapshot).
Out of scope for this iteration: catalog description_fr (vet-expert authoring required) and scope_disclaimer (vet legal review). They stay FR-only until an expert provides EN copy.
2. Architecture
localeStore (Zustand, persist key osteo:locale)
↓ subscribe
useT() hook → (key: string) => string // resolves against active dict
↓
Components/routes import useT, replace hardcoded FR with t('key.path')
↓
LanguageSwitcher in ReportHeader calls localeStore.setLocale(...)
formatDate(iso, locale) // src/lib/dates.ts — replaces formatDateFr
exportReportToPdf(report, { locale }) // explicit, no default
→ static eyebrows/labels via dict snapshot at call time
→ findings rendered via labelFrSnapshot or labelEnSnapshot per locale
→ header date via formatDate(iso, locale)
3. File plan
New files (src/)
src/state/localeStore.ts— Zustand store{ locale: Locale, setLocale(l: Locale) }, persists tolocalStorage.osteo:locale. Default'fr'if unset.src/i18n/types.ts—export type Locale = 'fr' | 'en';export type Dict = Record<string, string>.src/i18n/fr.ts— FR dict (~60 keys, flat snake_case namespaces e.g.editor.add_observation).src/i18n/en.ts— EN equivalents, same keys.src/i18n/index.ts—export const dicts: Record<Locale, Dict> = { fr, en };export function getDict(locale: Locale): Dict.src/i18n/useT.ts—useT(): (key: string) => string. Subscribes to localeStore. Missing key → returns key literal +console.warn(dev only).src/components/brand/LanguageSwitcher.tsx— segmentedFR | ENtoggle,aria-pressedper button, callssetLocale.
Edited files (src/)
src/lib/dates.ts— addformatDate(iso: string, locale: Locale): string; removeformatDateFr(callers migrate).src/components/report/ReportHeader.tsx— render<LanguageSwitcher/>next to Brand.src/app/routes/{Home,NewReport,Editor,NotFound}Route.tsx— strings viat().src/components/observation/{FindingsTreePicker,ObservationCard,FreeTextFindingInput,VertebraPicker,SeveritySelector}.tsx— strings viat(); finding leaf label =locale === 'en' ? labelEnSnapshot : labelFrSnapshot. The picker tree itself readsname_fr/name_enfrom the catalog by current locale.src/components/report/{PractitionerForm,AnimalForm,ConclusionPanel,NextAppointmentPicker}.tsx— strings viat().src/pdf/export.ts— signature changes toexportReportToPdf(report: Report, opts: { locale: Locale }). All callers updated.src/pdf/render/{header,footer,observationPage,conclusionPage}.ts— acceptlocaleargument; static labels (eyebrows, section titles, "Sévérité", "Conclusion", date prefix, page numbers if any) read from dict; finding labels via correct snapshot; date viaformatDate(_, locale).
Test files (tests/unit/)
state.localeStore.test.ts(NEW) — 3 tests: default fr, setLocale updates state, persists to localStorage on change.i18n.useT.test.tsx(NEW) — 2 tests: returns dict value for active locale, missing key returns key + warns.components.LanguageSwitcher.test.tsx(NEW) — 2 tests: click toggles store, aria-pressed reflects active locale.lib.dates.test.ts(EDIT) — replaceformatDateFrcases; coverformatDate('2026-05-20', 'fr')→'20 mai 2026';formatDate(..., 'en')→'May 20, 2026'.pdf.export.test.ts(EDIT) — add roundtrip per locale: export{ locale: 'fr' }and{ locale: 'en' }, re-import both, assert JSON attachment intact; assert returned PDF bytes differ; minimal byte presence check is unreliable for subset fonts (LRN-016) so cover via the imported JSON only.
4. Dict key conventions
- Flat namespace
<area>.<key>(e.g.editor.add_observation,pdf.eyebrow_observation). - Keys are snake_case English.
- Values are the human string.
- Both dicts have the same set of keys — verify via a single unit test that compares
Object.keys(fr).sort()toObject.keys(en).sort().
5. Locale resolution rules
| Source | Behavior |
|---|---|
localStorage.osteo:locale present and valid |
use it |
| Missing or invalid | default 'fr', do not write back yet |
setLocale(l) |
update store + write localStorage.osteo:locale = l |
localStorage write fails |
swallow, in-memory only, no user error |
PDF export does not default a locale — caller must pass it. Route layer reads the store at the export call site.
6. Out of scope (explicit)
- Catalog
description_frandscope_disclaimertranslation (vet-expert / legal pass needed). - Native
input[type=date]widget labels (browser/OS). - Brand identity strings (env-driven via
useConfig()). - Zod schema error messages emitted to console (dev-only).
7. Acceptance criteria
- Switching the locale updates every visible UI string at the next render.
- Locale persists across reload (verifiable in QA via DevTools localStorage).
- Re-importing a PDF does NOT change the active locale — the imported report uses whatever the store currently holds for next export.
- PDF exports in
'fr'and'en'have different static eyebrow / section / date strings; the embedded JSON is byte-identical between the two locales for the sameReport(locale lives outside the report). - 139 existing tests + 11 new tests = 150+ pass. Lint clean. Typecheck clean. Vite build OK.
8. Risks / open questions
- Risk: forgotten hardcoded FR strings. Mitigation: grep-pass over
src/after migration for'É','è','à',' du ','pour'etc. as a heuristic + verify in QA. - Risk: changing
formatDateFr→formatDatebreaks PDF render. Mitigation: TypeScript will flag every caller; covered by typecheck. - Open: should the dict be lazily loaded per locale? Decision: NO — both dicts are tiny (~3KB each), eager import in
i18n/index.tskeeps the bundle simple. Revisit if dict grows past 50KB.
9. Verification plan
pnpm typecheck
pnpm lint
pnpm test:run # 150+ tests green
pnpm build # bundle still <1MB main
Manual QA after build:
pnpm dev→ switch locale → all visible strings update.- Create a report → export FR PDF → re-import → re-export EN PDF → diff strings.
- Reload → locale persists.