# Translator's guide (i18n foundation — English shipped) This is the working guide for translating God's Eye View. The i18n foundation ships **English only**: the locale core, the English catalogs, and the parity gates are in, and every additional locale lands as its own stacked PR, one locale at a time, following the [locale-addition recipe](#the-locale-addition-recipe) below. That recipe is the deliberate design artifact of this phase — a locale is not "translated into the app", it is *shipped* through the same gate every time. ## Which locale ships, and which pair is offered One catalog ships: **en** (source of truth and unconditional fallback). Shipping is catalog-driven (`CATALOG_LOCALES` in `src/i18n/locale.js`): while only English ships, the built-in locale pair is en-only and the dock language switch renders a single EN button. Which pair the app *offers* is configuration, not code: `GEV_DEFAULT_LOCALE` and `GEV_SECONDARY_LOCALE` in `.env`, injected into the browser via vite defines. Both values are validated against the shipped catalogs — an invalid, unshipped, or degenerate pair (e.g. the same locale twice) degenerates to the built-in en-only shape with a dev-server-only `console.warn`. English is always resolvable — it is the fallback catalog — even when not part of the configured pair. ## How the catalog system works All application-owned UI text lives in four flat message catalogs (en today; one directory per locale once shipped): ```text src/i18n/ locale.js pair config + resolution + storage + / index.js catalog registry, t(), Intl formatters, DOM apply locales/en/{shell,cockpit,layers,setup}.js ``` | Namespace | Surface | | --- | --- | | `shell.*` | Document chrome: title, dock actions, panels, global status chip, sync chips, toasts, locale selector | | `cockpit.*` | Cockpit HUD readouts, Context panel, CCTV scene summary, Display/panel chrome, visual presets, Radio utility | | `layers.*` | Data-layer presentation: layer names, feed-state labels, row meta, vessel/flight/satellite/mission/CCTV/Radio/awareness cards and readouts | | `setup.*` | First-run launcher, key setup (POWER UP), scenes/director status, map-stack chips | Each catalog file exports `NAMESPACE` and a default map of namespace-relative keys; `mergeNamespace()` prefixes them (`cockpit.…`) and `buildCatalog()` rejects duplicates. English is the default and the fallback locale: a key missing in another locale renders its English value (dev-server-only `console.warn`). The en catalogs hold 912 keys (shell 34, cockpit 369, layers 388, setup 121). ## Key naming - Markup surfaces: `..` — e.g. `shell.panels.dataLayers`, `cockpit.readout.altitude`. - Runtime flows/states: `..` — e.g. `shell.status.loadingLiveData`, `layers.missions.telemetry.km`. - Names are semantic and stable. Never rename, reorder, or renumber an existing key: `data-i18n` attributes and runtime `t()` call sites in other files reference them. ## The locale-addition recipe Every locale PR follows the same steps, in this order. Nothing here is optional — the gates below fail the build if a step is skipped. 1. **Catalogs.** Copy `src/i18n/locales/en/` to `src/i18n/locales//` and translate all four files (`` is the primary language tag: `es`, not `es-419`). Keep the en key order, keep key names byte-identical, and translate VALUES only. A locale may never carry a key en lacks. 2. **Registration.** In `src/i18n/index.js`: add the four import lines and one `_NAMESPACES` array, then one entry in the `CATALOGS` map. Registration is append-only; nothing else in the file changes. 3. **Shipping.** Append `''` to `CATALOG_LOCALES` in `src/i18n/locale.js`. This single constant is what makes the locale normalizable-to-shipped: pair config, `?lang=`, storage, and the selector all read from it. Regional variants (`es-MX`, `es_419`) already normalize — locale-code hygiene is shipped ahead of the locales on purpose. 4. **Selector labels.** Append `'locale..ariaLabel': 'Switch to '` to the `shell` catalog of EVERY shipped locale (en included — the en catalog names the new button; the new catalog names the English one). `markupCoverage.test.mjs` requires a label for every shipped code in every catalog, so this cannot be forgotten. 5. **Plurals.** Plural entries are variant objects carrying a `{count}` placeholder, selected per active locale through `Intl.PluralRules`. English entries use `{ one, other }`. Your locale must keep every en variant and may add ONLY categories `Intl.PluralRules` reports valid for it (e.g. a Slavic locale adds `few`/`many`) — `catalog.test.mjs` enforces this shape against the live ICU data. Pin your locale's real-catalog plural agreement in `src/i18n/i18n.test.mjs` (one/few/many/other counts where relevant). 6. **Layout.** Prefer concise glossary-approved copy over CSS surgery; fixed-width `nowrap` panels must be checked at narrow viewports. A locale-scoped wrap rule (`html[lang=''] .cctv-controls { flex-wrap: wrap; }` in `src/ui/styles/cctv.css`) is added ONLY when the locale demonstrably clips, with a comment recording the measured widths — the English layout stays pixel-identical, and `repairPass.test.mjs` rejects a wrap rule shipping ahead of its locale. 7. **Gates.** `node --test src/i18n/` must be green with the strict parity gate ON: exact key-set equality with en, identical placeholder names, plural-shape superset. While a new catalog is a staged untranslated seed, CI may run with `GEV_I18N_REQUIRE_FULL_LOCALE_PARITY=0` (subset mode) — record every such flip here, and record the flip back. 8. **Docs.** Add the locale's section + glossary to this file, note it in `docs/CURRENT-STATE.md` (Internationalization) and `CHANGELOG.md`, and update the shipped-locales wording in `.env.example`. ## Append-only rules - New keys are appended to the END of the namespace file in EVERY shipped locale directory in the same change. Never edit another namespace's files, and never touch the registration arrays in `src/i18n/index.js` without re-reading this guide first. - A fifth namespace is a last resort (prefer fitting one of the four); its registration recipe is the same append-only pattern as a locale (step 2 of the recipe above), applied to every shipped locale at once. - Parity is enforced by tests, not goodwill: no locale may carry a key en lacks, and every shared key must keep identical placeholder names and a plural-variant set that includes every en variant plus only categories `Intl.PluralRules` reports for that locale (`src/i18n/catalog.test.mjs`). ## Placeholder, plural, and typography rules - Interpolation uses named `{camelCase}` placeholders: `'Flying to {place}…'`. The **same placeholder names must exist in every locale** — the parity gate fails on a renamed `{name}` because it would break interpolation at runtime. - Locale-aware numbers, dates, and relative times go through the `formatNumber` / `formatDate` / `formatRelativeTime` helpers in `src/i18n/index.js` — do not hand-format in a catalog call site. - Style: the English catalog is ALL-CAPS for tactical labels, readouts, and status text; translations follow the same convention in their script's norms. The `·` separator used between metadata segments is part of the surface style and is reproduced in translations. - Instrument codes stay identical across languages; units (KTS, FT, km, km²) are never translated. - Romance languages run ~25% longer than English and Slavic languages compound that on multi-word tactical labels — plan string budgets and check fixed-width panels before review (see step 6 above). ## Keep-English boundary (summary) Never catalog these — they are contracts, not copy: - Internal layer IDs and registry keys (`military-installations`, `ais-live-vessels`, stack ids). - Status enums and machine values (`FEED_STATE_LABELS` keys, lifecycle states, detection/context modes) — translate only the final label at the presentation boundary. - URL/hash contracts: share-link parameters, `?welcome=`, `?lang=`, storage schemas. - API fields, voice tool names/schemas, `/api/setup/*` payloads. - Provider/dataset/product names, callsigns, vessel/satellite/place names from data, news headlines, license/source attributions. - Console diagnostics, QA pin scripts, and existing exact-English test expectations. - User-authored content (annotations, labels drawn from live data). Adjudicated exceptions live in "Internationalization" in [`docs/CURRENT-STATE.md`](./CURRENT-STATE.md) (accepted deferrals — do not "fix" them silently). ## Glossary Approved recurring terms per locale. Each locale PR appends its glossary here (English term · translation · catalog evidence) so later translators reuse approved copy verbatim. None yet — the first entry arrives with the first translated locale. ## Running the i18n test gates ```sh node --test src/i18n/ # 40 tests: core + pair config, catalog parity, markup coverage, repair-pass anchors npm test # full suite (see below for the known environmental caveat) ``` - `src/i18n/i18n.test.mjs` — resolution precedence, guarded storage, fallback, interpolation, plural selection (contract + synthetic missing-category degradation; real-catalog plural pins arrive with each locale PR), DOM application. - `src/i18n/catalog.test.mjs` — key + placeholder + plural-shape parity for every shipped locale against en, strict `REQUIRE_FULL_PARITY` gate (vacuous while only en ships; each locale PR meets it from day one). - `src/i18n/markupCoverage.test.mjs` — every `data-i18n*` attribute in `index.html` must resolve in every shipped catalog; unknown attribute spellings fail loudly. - `src/i18n/repairPass.test.mjs` — byte-identity anchors for English literals; per-locale value anchors arrive with each locale PR. Full-suite caveat: `src/devFreshDotenv.test.mjs`'s external-keys provenance test fails when a provider key (e.g. `OPENAI_API_KEY`) is exported in the running shell — an environmental false positive unrelated to i18n.