Wire rust-i18n locale preference contract for panel i18n #274

Closed
opened 2026-11-16 09:03:33 +00:00 by glamourweaver · 2 comments
Member

What

Wire rust-i18n into the server/shared crates and expose a locale preference, per plan/shared/internationalisation.md (ADR 0013). This blocks #38, which needs a contract to build the panel's language switcher against.

Checked and confirmed missing (2026-11-16): no rust-i18n dependency anywhere in the workspace, no locales/ directory, no bundle files, no locale field on UserView/SessionUser, no locale-preference endpoint, no server-default-locale config.

Proposed contract (for agreement, not dictation — change it where it doesn't fit)

  • Bundles: crates/shared/locales/{en,nl}.yml, loaded via rust_i18n::i18n!("locales") in the shared crate so both server and client binaries can translate messages. Key naming: dot-path, e.g. panel.nav.devices.
  • Build-time check: a missing key in en.yml is a build error; a missing key in nl.yml (or any later locale) is a warning only; a stale key present in a translation but absent from en.yml is a build error. (Already specified in the plan doc, just needs the check implemented — Helpdesk has the same split if there's a pattern worth reusing.)
  • Server default locale: a config key (e.g. default_locale, env override DEFAULT_LOCALE), defaulting to en if unset. Per GRI-1884 / the no-hardcoding rule, this must not be a literal in code.
  • Per-user preference: add locale: string to UserView (returned by GET /session, POST /session, /setup), defaulting to the server default for a user who hasn't chosen one.
  • Setting it: either a dedicated PATCH /session/locale or folded into whatever the "update my profile" endpoint turns out to be (none exists yet either, as far as I could find) — backend engineer's call.
  • Client (signage device) messages: no per-user preference available; the device reads its own configured locale (falls back to en with nothing configured), per the plan doc's "client messages" section.

Done when

  • rust-i18n is wired into shared, with en and nl bundles (even if nl only covers a handful of strings at first — "a contributor who adds half a language has helped").
  • UserView carries locale, settable via an endpoint, with a documented contract (OpenAPI/types or a doc comment on the response type) that the frontend can code against.
  • The three key-check build outcomes (missing-in-English fails, missing-in-translation warns, stale-in-translation fails) exist in some form — a build script, a test, or a build.rs check.

Depends on

ADR 0013 (closed, #37).

Blocks

#38 (panel language switching — frontend, Glamourweaver).

## What Wire `rust-i18n` into the server/shared crates and expose a locale preference, per [plan/shared/internationalisation.md](../src/branch/dev/plan/shared/internationalisation.md) (ADR 0013). This blocks #38, which needs a contract to build the panel's language switcher against. Checked and confirmed missing (2026-11-16): no `rust-i18n` dependency anywhere in the workspace, no `locales/` directory, no bundle files, no locale field on `UserView`/`SessionUser`, no locale-preference endpoint, no server-default-locale config. ## Proposed contract (for agreement, not dictation — change it where it doesn't fit) - **Bundles**: `crates/shared/locales/{en,nl}.yml`, loaded via `rust_i18n::i18n!("locales")` in the `shared` crate so both `server` and `client` binaries can translate messages. Key naming: dot-path, e.g. `panel.nav.devices`. - **Build-time check**: a missing key in `en.yml` is a build error; a missing key in `nl.yml` (or any later locale) is a warning only; a stale key present in a translation but absent from `en.yml` is a build error. (Already specified in the plan doc, just needs the check implemented — Helpdesk has the same split if there's a pattern worth reusing.) - **Server default locale**: a config key (e.g. `default_locale`, env override `DEFAULT_LOCALE`), defaulting to `en` if unset. Per [GRI-1884](https://git.grimoirix.org/Grimoirix/grimoire-of-digital-signage) / the no-hardcoding rule, this must not be a literal in code. - **Per-user preference**: add `locale: string` to `UserView` (returned by `GET /session`, `POST /session`, `/setup`), defaulting to the server default for a user who hasn't chosen one. - **Setting it**: either a dedicated `PATCH /session/locale` or folded into whatever the "update my profile" endpoint turns out to be (none exists yet either, as far as I could find) — backend engineer's call. - **Client (signage device) messages**: no per-user preference available; the device reads its own configured locale (falls back to `en` with nothing configured), per the plan doc's "client messages" section. ## Done when - `rust-i18n` is wired into `shared`, with `en` and `nl` bundles (even if `nl` only covers a handful of strings at first — "a contributor who adds half a language has helped"). - `UserView` carries `locale`, settable via an endpoint, with a documented contract (OpenAPI/types or a doc comment on the response type) that the frontend can code against. - The three key-check build outcomes (missing-in-English fails, missing-in-translation warns, stale-in-translation fails) exist in some form — a build script, a test, or a `build.rs` check. ## Depends on ADR 0013 (closed, #37). ## Blocks #38 (panel language switching — frontend, Glamourweaver).
Member

Implemented and pushed: PR #276 (feature/GRI-2142-i18n-locale-contract → dev).

Wired:

  • rust-i18n in shared (bundles: crates/shared/locales/{en,nl}.yml) and server (each crate needs its own i18n! invocation — t! always expands to crate::_rust_i18n_t!, so a re-export of the macro alone would not reach another crate's bundles).
  • crates/shared/build.rs enforces the three key-check outcomes from the plan doc on every build (not a manually-run cargo i18n): missing-in-English fails, missing-in-translation warns, stale-in-translation fails. Verified all three by hand (temporarily broke each one, confirmed the right failure, reverted).
  • config.i18n.default_locale (env SIGNAGE_I18N_DEFAULT_LOCALE), refused at load for an unshipped locale.
  • users.locale (migration 0011, nullable = "use the server default").
  • UserView.locale on /setup, /session (GET/POST); PATCH /session/locale sets it, 400 unknown_locale otherwise.

Deviation worth flagging: ADR 0013 says to lean on rust-i18n's own tooling for the key checks rather than a bespoke one. I did that for bundle loading, but deliberately not via rust-i18n-extract (the library behind cargo i18n's own extractor) for the "used in code" scan — its Cargo.toml unconditionally depends on serde_yaml, which pulls in unsafe-libyaml (RUSTSEC-2024-0449, unmaintained, no safe upgrade), and this project's cargo deny gate correctly refuses that. build.rs's scan is a small hand-rolled literal-argument scanner instead (same shape as Helpdesk's own tk! scanner), with no new advisory surface. The bundle loader used for the other two checks is unaffected — it parses YAML with serde-saphyr, not serde_yaml.

Not wired: the client's own message screens (pending-registration, key-mismatch, etc.) — none of them call t!() yet, so there's nothing on that side for this issue to wire up. Left for whichever issue converts the first one.

All local gates green: cargo fmt, cargo clippy -D warnings, cargo test --workspace --all-targets (incl. a new session_locale_integration.rs, run against a real Postgres — 30/30 binaries), cargo test --doc, cargo deny check -D advisory-not-detected.

CI is queued on the PR (fj ci 276), ETA ~1h20m per the queue drain rate at the time of this comment.

Implemented and pushed: PR #276 (`feature/GRI-2142-i18n-locale-contract` → `dev`). **Wired:** - `rust-i18n` in `shared` (bundles: `crates/shared/locales/{en,nl}.yml`) and `server` (each crate needs its own `i18n!` invocation — `t!` always expands to `crate::_rust_i18n_t!`, so a re-export of the macro alone would not reach another crate's bundles). - `crates/shared/build.rs` enforces the three key-check outcomes from the plan doc on every build (not a manually-run `cargo i18n`): missing-in-English fails, missing-in-translation warns, stale-in-translation fails. Verified all three by hand (temporarily broke each one, confirmed the right failure, reverted). - `config.i18n.default_locale` (env `SIGNAGE_I18N_DEFAULT_LOCALE`), refused at load for an unshipped locale. - `users.locale` (migration `0011`, nullable = "use the server default"). - `UserView.locale` on `/setup`, `/session` (GET/POST); `PATCH /session/locale` sets it, `400 unknown_locale` otherwise. **Deviation worth flagging:** ADR 0013 says to lean on rust-i18n's own tooling for the key checks rather than a bespoke one. I did that for bundle loading, but deliberately *not* via `rust-i18n-extract` (the library behind `cargo i18n`'s own extractor) for the "used in code" scan — its `Cargo.toml` unconditionally depends on `serde_yaml`, which pulls in `unsafe-libyaml` (RUSTSEC-2024-0449, unmaintained, no safe upgrade), and this project's `cargo deny` gate correctly refuses that. `build.rs`'s scan is a small hand-rolled literal-argument scanner instead (same shape as Helpdesk's own `tk!` scanner), with no new advisory surface. The bundle loader used for the other two checks is unaffected — it parses YAML with `serde-saphyr`, not `serde_yaml`. **Not wired:** the client's own message screens (pending-registration, key-mismatch, etc.) — none of them call `t!()` yet, so there's nothing on that side for this issue to wire up. Left for whichever issue converts the first one. All local gates green: `cargo fmt`, `cargo clippy -D warnings`, `cargo test --workspace --all-targets` (incl. a new `session_locale_integration.rs`, run against a real Postgres — 30/30 binaries), `cargo test --doc`, `cargo deny check -D advisory-not-detected`. CI is queued on the PR (`fj ci 276`), ETA ~1h20m per the queue drain rate at the time of this comment.
Member

CI is green on PR #276 (#276), commit 4ed1a001: clippy, fmt, cargo deny + advisories, cargo test (incl. new session_locale_integration.rs against real Postgres), frontend-web, repository boundary, pre-push hook all passing. Handing off to the CTO for code review and merge into dev.

CI is green on PR #276 (https://git.grimoirix.org/Grimoirix/grimoire-of-digital-signage/pulls/276), commit 4ed1a001: clippy, fmt, cargo deny + advisories, cargo test (incl. new session_locale_integration.rs against real Postgres), frontend-web, repository boundary, pre-push hook all passing. Handing off to the CTO for code review and merge into dev.
vivy closed this issue 2026-11-16 11:07:59 +00:00
Sign in to join this conversation.
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grimoirix/grimoire-of-digital-signage#274
No description provided.