From d559f565ac0467729e88dc3df2b730772609468b Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Wed, 20 May 2026 06:44:28 +0200 Subject: [PATCH] docs(spec): B3 i18n FR/EN site + PDF design Approved design before implementation. Locale = render preference (store, not Report schema). PDF export takes explicit locale arg. Finding leaf labels via existing dual snapshot; catalog descriptions + scope_disclaimer stay FR-only this iteration. Co-Authored-By: Claude Opus 4.7 --- .../specs/2026-05-20-b3-i18n-fr-en-design.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-20-b3-i18n-fr-en-design.md diff --git a/docs/superpowers/specs/2026-05-20-b3-i18n-fr-en-design.md b/docs/superpowers/specs/2026-05-20-b3-i18n-fr-en-design.md new file mode 100644 index 00000000..a5504839 --- /dev/null +++ b/docs/superpowers/specs/2026-05-20-b3-i18n-fr-en-design.md @@ -0,0 +1,115 @@ +# 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 to `localStorage.osteo:locale`. Default `'fr'` if unset. +- `src/i18n/types.ts` — `export type Locale = 'fr' | 'en'`; `export type Dict = Record`. +- `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 = { 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` — segmented `FR | EN` toggle, `aria-pressed` per button, calls `setLocale`. + +### Edited files (`src/`) + +- `src/lib/dates.ts` — add `formatDate(iso: string, locale: Locale): string`; remove `formatDateFr` (callers migrate). +- `src/components/report/ReportHeader.tsx` — render `` next to Brand. +- `src/app/routes/{Home,NewReport,Editor,NotFound}Route.tsx` — strings via `t()`. +- `src/components/observation/{FindingsTreePicker,ObservationCard,FreeTextFindingInput,VertebraPicker,SeveritySelector}.tsx` — strings via `t()`; finding leaf label = `locale === 'en' ? labelEnSnapshot : labelFrSnapshot`. The picker tree itself reads `name_fr`/`name_en` from the catalog by current locale. +- `src/components/report/{PractitionerForm,AnimalForm,ConclusionPanel,NextAppointmentPicker}.tsx` — strings via `t()`. +- `src/pdf/export.ts` — signature changes to `exportReportToPdf(report: Report, opts: { locale: Locale })`. All callers updated. +- `src/pdf/render/{header,footer,observationPage,conclusionPage}.ts` — accept `locale` argument; static labels (eyebrows, section titles, "Sévérité", "Conclusion", date prefix, page numbers if any) read from dict; finding labels via correct snapshot; date via `formatDate(_, 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) — replace `formatDateFr` cases; cover `formatDate('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 `.` (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()` to `Object.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_fr` and `scope_disclaimer` translation (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 same `Report` (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` → `formatDate` breaks 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.ts` keeps the bundle simple. Revisit if dict grows past 50KB. + +## 9. Verification plan + +```bash +pnpm typecheck +pnpm lint +pnpm test:run # 150+ tests green +pnpm build # bundle still <1MB main +``` + +Manual QA after build: +1. `pnpm dev` → switch locale → all visible strings update. +2. Create a report → export FR PDF → re-import → re-export EN PDF → diff strings. +3. Reload → locale persists.