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:
Frederic Jung 2026-10-27 11:27:11 +01:00
parent 9043af5ab0
commit 0057e74472
No known key found for this signature in database
14 changed files with 253 additions and 63 deletions

View file

@ -7,7 +7,8 @@ the build joins them into **one self-contained `index.html`** (one inline `<styl
```
src/ the game page, in pieces
index.html shell: <head>, static markup, the language loader, two @include lines
index.html shell: <head>, static markup, the language loader, the @include lines
i18n/en.js the English for every label → inlined at the top of the page's <script>
styles/NN-*.css → pasted into the page's <style>, in path order
game/NN-area/NN-*.js → pasted into the page's <script>, in path order
site/ static files copied to the build as they are (dictionaries, icons, sw.js…)
@ -54,22 +55,24 @@ Development runs on `npm run dev` (assembles on every request, reloads on save);
| Path | What it is |
| --- | --- |
| `site/i18n/it.js`, `pt.js`, `fr.js` | Dictionaries: English text → translation, one entry per line, sorted; loaded only for that language |
| `src/i18n/en.js` | English: label → text, one entry per line, sorted; inlined into the page by `<!-- @include i18n -->` |
| `site/i18n/it.js`, `pt.js`, `fr.js` | Translations: label → text, the same layout; loaded only for that language |
| `site/sw.js` | Service worker: network-first for pages, stale-while-revalidate for assets. Cache name is stamped with the version |
| `site/site.webmanifest`, icons, `404.html`, `CNAME`, `robots.txt`, `sitemap.xml`, `llms.txt` | PWA and GitHub Pages files, copied as they are |
| `scripts/lib/page.js` | Assembles the page from `src/` (also from a git ref with `--ref`, for performance baselines) |
| `scripts/lib/compile-labels.js` | Shrinks labels to short ids in the shipped page and dictionaries |
| `scripts/build.js` | Builds `_site/` for GitHub Pages: copies `site/`, writes the page, stamps `__VERSION__`/`__BUILD_DATE__`, bakes release notes, writes `version.json` |
| `scripts/dev.js` | `npm run dev`: development server, no dependencies |
| `scripts/test.js` | `npm test`: runs every `tests/*.test.js` |
| `scripts/release-notes.js` | Extracts a version's CHANGELOG bullets |
| `scripts/perf-bench.js`, `perf-browser.js`, `perf-stats.js`, `perf-fixture.js` | Big-network benchmark, base vs head, headless and in Chromium as a desktop and a throttled phone, with a significance test per row (posted on every PR by `perf.yml` + `perf-comment.yml`), and the generator of its save, `tests/fixtures/big-network.json` |
| `scripts/i18n-check.js`, `scripts/i18n-add.js`, `scripts/lib/dict.js` | Translation coverage and dictionary order; adding, renaming and removing entries |
| `scripts/legacy/` | The splitter that made `src/` from the old `site/index.html`, and `port-branch.js`, which carries older branches over |
| `scripts/legacy/` | The splitter that made `src/` from the old `site/index.html` (and gave its text labels), and `port-branch.js`, which carries older branches over |
| `tests/harness.js` | Loads the assembled page in jsdom with a seeded `Math.random` and a fake canvas |
| `.github/workflows/ci.yml` | Tests and build on every push and PR |
| `.github/workflows/auto-release.yml` | On a `package.json` version bump on `main`: test, tag, GitHub release from the CHANGELOG, start the deploy |
| `.github/workflows/release.yml` | Builds and deploys to GitHub Pages, the only workflow that can |
| `docs/adr/` | Decisions: GitHub Pages only (0001), one page assembled at build (0002) |
| `docs/adr/` | Decisions: GitHub Pages only (0001), one page assembled at build (0002), translations by label (0003) |
## Globals
@ -150,11 +153,17 @@ Served share per city (`sfOf`) drives eyeball revenue and customer mood.
## Translations
- `tr(text, vars)` looks up `DICT[text]` and fills `{placeholders}`; `trn(one, other, n)`
picks the plural; `N_(text)` marks a literal for the checker and translates later.
- Static markup uses `data-i18n`; `i18nDom()` swaps it at boot.
- The English text is the key, so changing English text means updating the key in
every dictionary.
Text is keyed by label ([ADR 0003](adr/0003-translations-by-label.md)):
- `tr('area.label', vars)` looks up `DICT['area.label']` and fills `{placeholders}`; `trn('area.label', n)`
picks `one` or `other` of a plural; `N_('area.label')` marks a label kept in a table or a save, translated
where it is shown.
- `DICT` is the English (`src/i18n/en.js`, inlined into the page) with the player's language
(`site/i18n/<lang>.js`) laid over it. English text from saves of 1.33 and older still finds its translation.
- Static markup uses `data-i18n="label"`, `data-i18n-aria-label`, `data-i18n-title`; `i18nDom()` swaps it at boot.
- The build swaps labels for short ids in the shipped page and dictionaries (`scripts/lib/compile-labels.js`);
`N_()` labels stay whole because saves keep them.
- `npm run i18n:check` checks the English against the code and every translation against the English.
## Tests

View 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.