Files
faunosteo/docs/history/superpowers/specs/2026-05-20-b3-i18n-fr-en-design.md
T
bchanot 02052f3622 docs(docs): restore 2026-05 design specs and plans under docs/history
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.
2026-10-08 21:51:13 +02:00

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 to localStorage.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 — 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 <LanguageSwitcher/> 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 <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() 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

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.