Ship short ids instead of labels; checker, tests and docs for labels
The build swaps every label for a short id in the shipped page, the inlined English and the translation files (scripts/lib/compile-labels.js). Labels passed to N_() stay whole because saves keep them. Against 1.33: page +4% gzipped (321 -> 335 KB), translations -40% (it.js 143 -> 85 KB); routing, day, panels, dashboard, map and boot time unchanged. - i18n-check rejects labels the build cannot see (outside tr/trn/N_) - tests/pages.test.js plays the shipped page in English, Italian and French - docs/adr/0003, add-strings skill, ARCHITECTURE, README, CONTRIBUTING, CLAUDE.md describe labels
This commit is contained in:
parent
9043af5ab0
commit
0057e74472
14 changed files with 253 additions and 63 deletions
57
docs/adr/0003-translations-by-label.md
Normal file
57
docs/adr/0003-translations-by-label.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
# ADR 0003: Translations are keyed by labels, not by English text
|
||||
|
||||
- Status: accepted
|
||||
- Date: 2026-10-27
|
||||
|
||||
## Context
|
||||
|
||||
Until 1.33 the English text was the key: code said `tr('Delivery: 2 to 6 weeks')`, and every dictionary
|
||||
repeated that English as its key, `"Delivery: 2 to 6 weeks":"Consegna: da 2 a 6 settimane"`. So each of
|
||||
the ~2,900 strings existed four times (code, it, pt, fr), and more with every language. Fixing a typo in
|
||||
English meant renaming the key in every dictionary in the same change, or every translation silently
|
||||
fell back to English. Long sentences as keys made dictionary diffs hard to read and easy to conflict.
|
||||
|
||||
## Decision
|
||||
|
||||
- Code uses **labels**: `tr('pnis.delivery_2_to_6_weeks')`, `trn('save.n_pop', n)`, `N_('common.optics')`.
|
||||
A label is `area.words`: the area is where the text is used (`pnis`, `own_cable`, `page`, or `common`
|
||||
for text used in several places and short shared words), the words are a few of its first words.
|
||||
- **English is a dictionary too**, `src/i18n/en.js`, in the same format as the translations. It is part of
|
||||
the page source: the build inlines it into the game script, so English players load nothing extra
|
||||
(see [ADR 0002](0002-one-page-assembled-at-build.md)). Translations stay static files,
|
||||
`site/i18n/<lang>.js`, loaded only for that language.
|
||||
- **Plurals are one label** with `{"one": …, "other": …}` in every language: `trn('save.n_pop', n, vars)`.
|
||||
- **Static markup** says `data-i18n="label"` (and `data-i18n-aria-label`, `data-i18n-title`) and keeps its
|
||||
English text, so the page still reads in English without JavaScript and for search engines. The checker
|
||||
makes sure that English matches `en.js`.
|
||||
- At runtime, `DICT` is the English with the player's language laid over it: a missing translation shows
|
||||
the English, an unknown label shows itself (the checker makes sure there are none).
|
||||
|
||||
## Consequences
|
||||
|
||||
- **Changing English wording is one line** in `en.js`. If the meaning changes, give it a new label
|
||||
instead (`scripts/i18n-add.js --rename` moves one everywhere), so translators see it as new and the
|
||||
old translation does not linger with the wrong meaning.
|
||||
- **`npm run i18n:check`** verifies that every label used in `src/` is defined in English, every
|
||||
English label is used, every translation keeps its English's placeholders, HTML tags and plural forms,
|
||||
and every dictionary is sorted.
|
||||
- **Saves:** a few things in a save hold text to show later (the peering inbox log, sold-out reasons,
|
||||
attack names). New saves hold labels. Saves from 1.33 and older hold the English text; `tr()` maps it
|
||||
back to its label the first time it sees one, so old saves still show the player's language.
|
||||
- **Translators** read `src/i18n/en.js` next to their file; both are sorted by the same labels, so the
|
||||
same line numbers line up.
|
||||
- **The shipped page uses short ids, not labels.** Shipped as written, every label would be in the page
|
||||
twice (in the code and as a key of the inlined English): about 20% more page after compression. So
|
||||
the build (`scripts/lib/compile-labels.js`) gives every label a short id (`tr('1a')`) in the code, the
|
||||
markup and every dictionary. Labels passed to `N_()` keep their name in the shipped page, because the
|
||||
game stores those in saves and an id would mean something else in the next release. The checker
|
||||
rejects a label that is not the first argument of `tr()`/`trn()`/`N_()`, since the build cannot see it.
|
||||
`src/`, `npm run dev` and the tests all use the readable labels; `tests/pages.test.js` plays the
|
||||
shipped page in English, Italian and French.
|
||||
- **Performance:** measured against 1.33 on the big-network save, routing, a game day, panels, the
|
||||
dashboard and the map are all unchanged, and boot time too. The page is about 4% bigger after
|
||||
compression (321 → 335 KB): the English moved from the code into its own dictionary, with an id each.
|
||||
The translation files are about 40% smaller (it.js 143 → 85 KB), so Italian, Portuguese and French
|
||||
players download less than before. `tr()` is still one property lookup.
|
||||
- Branches from before this change are converted by `scripts/legacy/port-branch.js` like the rest of the
|
||||
split: their English-keyed calls and dictionaries get the same labels.
|
||||
Loading…
Add table
Add a link
Reference in a new issue