seriesoftubes/docs/adr/0003-translations-by-label.md

4.2 KiB

ADR 0003: Translations are keyed by labels, not by English text

  • Status: accepted
  • Date: 2026-10-27

Context

Until 1.34 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). 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 before labels (1.34 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.34 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.