Translate the front with a language provider (English + French)

root commented

2026-10-05 08:17:34 +00:00

(Migrated from gitlab.core-project.space)

Imported from GitHub amaurycoudr/chess-project#242, opened by @amaurycoudr on 2026-10-05 08:17 UTC.
Closed on GitHub on 2026-10-05 10:11 UTC as completed.

Problem Statement

Every word the app shows is hard-coded English, spread over constants in each vertical (status lines, refusals, confirmations, presence, offers, home). A French-speaking player cannot use the app in French, and changing any wording means hunting through components.

Solution

The front reads all its copy from one message catalogue, in English and French. The language follows the browser on first visit and can be switched from the site header; the choice is remembered on that device. The library is Paraglide JS (inlang): messages compile to typed functions, unused ones are tree-shaken, and it ships a Vite plugin.

User Stories

As a player whose browser is in French, I want the app in French on my first visit, so that I don't have to look for a setting.
As a player whose browser is in any other language, I want the app in English, so that I always get a complete language.
As a player, I want to switch between English and French from the site header, so that I can override my browser.
As a player, I want my choice remembered on this device, so that I don't switch again on every visit.
As a player, I want every message translated — status lines, actions and their confirmations, offers, presence, toasts, refusals, home, local game — so that no English is left behind in French.
As a screen-reader user, I want the page's lang to match the language shown, so that it is read with the right voice.

Seams

Views through each vertical's harness and MSW (view tests): the home, local and room views rendered with a given browser language and with a stored choice. Covers stories 1–6.

Implementation Decisions

Paraglide JS with its Vite plugin in the front only. Locales en (source, fallback) and fr.
Locale resolution order: stored choice in localStorage, then the browser language, then en. localStorage reads are guarded like the Seat token's.
Messages take parameters instead of concatenated fragments (Colors, Draw reasons, Offer kinds), so French can agree in gender and word order ("Les Blancs ont abandonné").
Notation (SAN, Room codes) is never translated.
The API keeps returning refusal codes only; translation stays in the front.
A language switch in the site header.
Needs a new ADR (front i18n with Paraglide, rejected: react-i18next, Lingui), written in its own PR per CLAUDE.md.

Testing Decisions

Prior art: the room view tests (room.test.tsx, room-presence.test.tsx) and the home view tests.
Unhappy paths: unsupported browser language falls back to English; a blocked localStorage still renders (browser language wins).
apps/e2e keeps asserting English strings; Playwright's default locale is English, so it stays green without changes.

Out of Scope

Any language other than English and French.
Locale in the URL (/fr/...).
Translating docs, ADRs or commit conventions.

Further Notes

The room rail spec rewrites much of the room copy; it should land after this one so its new strings go straight into the catalogue.

> _Imported from GitHub [amaurycoudr/chess-project#242](https://github.com/amaurycoudr/chess-project/issues/242), opened by [@amaurycoudr](https://github.com/amaurycoudr) on 2026-10-05 08:17 UTC._ > _Closed on GitHub on 2026-10-05 10:11 UTC as completed._  --- ## Problem Statement Every word the app shows is hard-coded English, spread over constants in each vertical (status lines, refusals, confirmations, presence, offers, home). A French-speaking player cannot use the app in French, and changing any wording means hunting through components. ## Solution The front reads all its copy from one message catalogue, in English and French. The language follows the browser on first visit and can be switched from the site header; the choice is remembered on that device. The library is **Paraglide JS** (inlang): messages compile to typed functions, unused ones are tree-shaken, and it ships a Vite plugin. ## User Stories 1. As a player whose browser is in French, I want the app in French on my first visit, so that I don't have to look for a setting. 2. As a player whose browser is in any other language, I want the app in English, so that I always get a complete language. 3. As a player, I want to switch between English and French from the site header, so that I can override my browser. 4. As a player, I want my choice remembered on this device, so that I don't switch again on every visit. 5. As a player, I want every message translated — status lines, actions and their confirmations, offers, presence, toasts, refusals, home, local game — so that no English is left behind in French. 6. As a screen-reader user, I want the page's `lang` to match the language shown, so that it is read with the right voice. ## Seams - **Views through each vertical's harness and MSW** (view tests): the home, local and room views rendered with a given browser language and with a stored choice. Covers stories 1–6. ## Implementation Decisions - Paraglide JS with its Vite plugin in the front only. Locales `en` (source, fallback) and `fr`. - Locale resolution order: stored choice in `localStorage`, then the browser language, then `en`. `localStorage` reads are guarded like the Seat token's. - Messages take parameters instead of concatenated fragments (Colors, Draw reasons, Offer kinds), so French can agree in gender and word order ("Les Blancs ont abandonné"). - Notation (SAN, Room codes) is never translated. - The API keeps returning refusal codes only; translation stays in the front. - A language switch in the site header. - **Needs a new ADR** (front i18n with Paraglide, rejected: react-i18next, Lingui), written in its own PR per CLAUDE.md. ## Testing Decisions - Prior art: the room view tests (`room.test.tsx`, `room-presence.test.tsx`) and the home view tests. - Unhappy paths: unsupported browser language falls back to English; a blocked `localStorage` still renders (browser language wins). - `apps/e2e` keeps asserting English strings; Playwright's default locale is English, so it stays green without changes. ## Out of Scope - Any language other than English and French. - Locale in the URL (`/fr/...`). - Translating docs, ADRs or commit conventions. ## Further Notes The room rail spec rewrites much of the room copy; it should land after this one so its new strings go straight into the catalogue.

root commented

2026-10-05 08:17:34 +00:00

(Migrated from gitlab.core-project.space)

GitHub issue relations, imported as "related" links (GitLab CE has no sub-issues or blocking links).

Blocking: #253, #246, #245

> _GitHub issue relations, imported as "related" links (GitLab CE has no sub-issues or blocking links)._  - Blocking: #253, #246, #245

root (Migrated from gitlab.core-project.space) closed this issue

2026-10-05 10:11:15 +00:00

root commented

2026-10-13 08:39:13 +00:00

(Migrated from gitlab.core-project.space)

mentioned in issue #243