galaxy-game/ui/docs/i18n.md

i18n (UI)

The UI client ships with a minimal locale primitive used by the login form, the root layout, and the lobby. The goal is just enough infrastructure to translate user-visible strings, switch the active language at runtime, and forward the caller's choice to the gateway. Swapping this primitive for a fuller solution with message-format pluralisation, lazy loading, and translator workflows is deferred to the finalization plan (../Plan-finalize.md); until then, the surface here covers every authenticated and unauthenticated screen the client renders.

Surface

src/lib/i18n/
├── index.svelte.ts       # I18nStore singleton, types, SUPPORTED_LOCALES
└── locales/
    ├── en.ts             # English dictionary (default, source of truth)
    └── ru.ts             # Russian dictionary (mirrors en.ts keys)

The exported singleton (i18n) is a Svelte 5 runes class with one reactive field, locale, and a t(key, params?) lookup. Components read translations through i18n.t('login.title') and re-render automatically when i18n.locale changes.

The runes singleton is a .svelte.ts file because Svelte 5 only processes $state runes inside .svelte, .svelte.js, and .svelte.ts modules.

Adding a language

Two-step change inside src/lib/i18n/:

1. Drop locales/<bcp47-primary-subtag>.ts mirroring the shape of locales/en.ts. The TypeScript signature on each non-English file is Record<keyof typeof en, string>, so the compiler refuses to build until every key in en.ts is translated.
2. Register the new file in the SUPPORTED_LOCALES array in index.svelte.ts. That single list drives the language picker (UI) and the runtime lookup table.

For example, adding French:

// src/lib/i18n/locales/fr.ts
import type en from "./en";
const fr: Record<keyof typeof en, string> = {
    "common.language": "langue",
    /* …translate every other key… */
};
export default fr;

// src/lib/i18n/index.svelte.ts
import frTranslations from "./locales/fr";

export type Locale = "en" | "ru" | "fr";

export const SUPPORTED_LOCALES: readonly LocaleEntry[] = [
    { code: "en", nativeName: "English", translations: enTranslations },
    { code: "ru", nativeName: "Русский", translations: ruTranslations },
    { code: "fr", nativeName: "Français", translations: frTranslations },
];

No other code change is required: the picker, the detection helper, the t() function and the gateway forwarding all derive from SUPPORTED_LOCALES.

Detection

detectInitialLocale(preferences?) returns the first SUPPORTED_LOCALES entry whose code matches the primary subtag of any preference, or DEFAULT_LOCALE (English) when nothing matches.

The web target calls it without arguments, in which case the helper reads navigator.languages (or navigator.language as fallback). Native wrappers (Wails, Capacitor) will pass their system locale once the desktop/mobile targets land (see ../ROADMAP.md); the helper is platform-agnostic by design.

The boot locale resolves once at module load (no async init): an explicit stored choice wins, otherwise browser/system detection, otherwise DEFAULT_LOCALE. Callers that mutate the locale (the language pickers on /login and in the account menu) call i18n.setLocale(next), which persists the choice to localStorage (key galaxy-locale) so it survives reloads. An unrecognised stored value is ignored and falls back to detection.

Forwarding the locale to the gateway

The login form passes the active i18n.locale to sendEmailCode(baseUrl, email, { locale }). The auth API places the value inside the JSON body (locale field) rather than the Accept-Language header:

await sendEmailCode(GATEWAY_BASE_URL, trimmed, { locale: i18n.locale });

The body field is the canonical channel because Safari/WebKit silently drops JS-set Accept-Language headers (a long-standing WebKit fingerprinting mitigation). The gateway reads the body field with priority over the request Accept-Language, and non-Safari clients can still rely on the header alone — the gateway treats body and header as a single fallback chain. See gateway/internal/restapi/public_auth.go for the resolution path and docs/FUNCTIONAL.md §1.2 for the contract.

The confirm-email-code endpoint does not carry the locale. Per docs/FUNCTIONAL.md §1.3, the preferred language is captured at challenge issuance and replayed from the challenge row.

Key conventions

• Dotted keys grouped by feature area: login.*, lobby.*, common.*. New screens own their own prefix.
• Templates may carry simple {name} placeholders. The t() helper substitutes them with the caller-provided value via plain string replacement; values are written to the DOM unescaped, so callers must feed user-safe strings.
• Lookup falls back to the default locale and finally to the literal key when a key is missing in the active locale. The TypeScript signature on each locale file enforces complete coverage at build time, so runtime fallback is the safety net for a freshly added language that has not finished its translation pass.
• The translation file is the single source of truth — components never hardcode user-visible English text; everything goes through i18n.t(...).

Testing

• tests/i18n.test.ts covers detectInitialLocale, i18n.setLocale, parameter interpolation, and the unknown-key fallback.
• tests/i18n-completeness.test.ts enforces en/ru key-set parity (no key present in one locale but missing in the other), non-empty values, and locale persistence (a stored choice is restored on the next load).
• tests/login-page.test.ts asserts the language picker renders with native names, switching the locale re-renders the form text, and sendEmailCode receives the active locale.
• tests/auth-api.test.ts asserts the locale is forwarded through the JSON body of send-email-code.
• tests/e2e/auth-flow.spec.ts covers the dropdown-driven switch end-to-end on every Playwright project, including Safari (where Accept-Language is unsettable from JS).