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 <noreply@anthropic.com>
This commit is contained in:
1 parent
bffa6fba26
commit
d559f565ac
1 file changed
+115
@@ -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<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
|
||||
|
||||
```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.
|
||||
Reference in new issue
Block a user