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
|
|
@ -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
|
||||
|
||||
|
|
|
|||
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