diff --git a/.claude/skills/add-strings/SKILL.md b/.claude/skills/add-strings/SKILL.md index ab600c6..38f4c0e 100644 --- a/.claude/skills/add-strings/SKILL.md +++ b/.claude/skills/add-strings/SKILL.md @@ -1,47 +1,66 @@ --- name: add-strings -description: Add or change player-facing text in Series of Tubes and keep every translation (site/i18n/*.js) complete. +description: Add or change player-facing text in Series of Tubes: labels in the code, English in src/i18n/en.js, and every translation (site/i18n/*.js) kept complete. --- # Adding or changing player-facing text -The English text is the translation key. Every string a player can see must go -through the translation helpers and have an entry in every dictionary in `site/i18n/` -(Italian `it.js`, Portuguese `pt.js`, French `fr.js`). The code is in `src/`. +Text is keyed by **label** ([docs/adr/0003-translations-by-label.md](../../../docs/adr/0003-translations-by-label.md)). +The code says `tr('pnis.delivery_2_to_6_weeks')`; the English is in `src/i18n/en.js`; Italian, Portuguese +and French are `site/i18n/it.js`, `pt.js`, `fr.js`. Every label the code uses needs English, and every +language needs every label. ## In the code -- `tr('Text with {name}', {name})`: translate now and fill placeholders. -- `trn('{n} router', '{n} routers', n, vars)`: plurals; both forms are keys. -- `N_('Text')`: marks a literal kept in a table for later `tr()` (e.g. labels stored in - constants). Call `tr(x)` where it's shown. -- Static HTML: add `data-i18n` to the element; `aria-label` and `title` attributes are - collected automatically. -- Text must be a string literal inside the call, or the checker can't see it. -- Keep HTML (``, `
`, ``) and `{placeholders}` identical in translations. -- Don't build sentences by concatenating translated fragments; translate whole sentences. +- `tr('area.label', {name})`: translate now and fill `{placeholders}`. +- `trn('area.label', n, vars)`: plurals. One label, whose entries are `{"one": "…", "other": "…"}`; + `{n}` is filled in for you. +- `N_('area.label')`: a label kept in a table or a save and translated where it is shown with + `tr(x)`. Anything stored in `S` must be an `N_()` label (or an index), never translated text and never + a label written any other way: the build shortens every label it sees in `tr()`/`trn()` to an id that + changes between releases, and keeps the `N_()` ones whole. +- The label is always a string literal, the first argument of `tr`/`trn`/`N_`. A label anywhere else + (`const x='pnis.ready'`) is an error in `npm run i18n:check`. +- Static HTML in `src/index.html`: `data-i18n="area.label"` on the element, with its English inside it; + `data-i18n-aria-label="…"` and `data-i18n-title="…"` next to those attributes. +- Keep HTML (``, `
`, ``) and `{placeholders}` identical in every language. +- Don't build sentences from translated fragments; translate whole sentences. -## In the dictionary +## Naming a label -`site/i18n/.js` is one object, `"English":"Translation",` per line, **sorted by the English -text**. Sorted files mean two pull requests that add strings touch different lines instead of both -appending at the end. Don't edit the lines by hand; use the script, which quotes correctly, keeps the -order and works on every dictionary at once: +`area.some_words`: the area is the file or topic it is shown in (`pnis`, `own_cable`, `dashboard`, +`page` for the static markup), or `common` for text used all over and short everyday words +(`common.close`, `common.customers`). The words are the first few words of the English, lower case, +`_` between them: `pnis.ready_in_about_n_days`. Labels are only for finding things; players never see +them. Reuse an existing label when the text and the meaning are the same (`grep -n '"Close"' src/i18n/en.js`). + +## In the dictionaries + +Every dictionary is one entry per line, **sorted by label**, so new text from different pull requests +lands on different lines. Don't edit them by hand; the script writes English and translations together: ```bash cat > /tmp/strings.json <<'JSON' { - "it": { "New English text": "Nuovo testo italiano", "Text that was removed": null }, - "pt": { "New English text": "Novo texto em português" }, - "fr": { "New English text": "Nouveau texte en français" } + "en": { "pnis.ready_in_about_n_days": "Ready in about {n} days", + "save.n_pop": { "one": "{n} POP", "other": "{n} POPs" } }, + "it": { "pnis.ready_in_about_n_days": "Pronto tra circa {n} giorni", + "save.n_pop": { "one": "{n} POP", "other": "{n} POP" } }, + "pt": { "pnis.ready_in_about_n_days": "Pronto em cerca de {n} dias" }, + "fr": { "pnis.ready_in_about_n_days": "Prêt dans environ {n} jours" } } JSON -node scripts/i18n-add.js /tmp/strings.json # a string adds or replaces, null removes -node scripts/i18n-add.js --rename "Old English" "New English" # English text changed: move the key everywhere +node scripts/i18n-add.js /tmp/strings.json # a string or {one, other} sets an entry, null removes it +node scripts/i18n-add.js --rename old.label new.label # in every dictionary and everywhere in src/ ``` -If a dictionary got out of order anyway (a hand edit, a merge), `npm run i18n:fix` sorts it again; -`npm run i18n:check` fails until it is sorted. +- **Changing English wording** (a typo, a clearer phrase, same meaning): change only the English. The + translations stay right. +- **Changing the meaning**: give the text a new label (`--rename`, then update the English and every + translation), so no language keeps a translation that now says something else. +- **Removing text**: `null` under `"en"` removes the label from every dictionary. + +`npm run i18n:fix` re-sorts a dictionary that got out of order (a hand edit, a merge). ## Italian style @@ -52,6 +71,6 @@ into an Italian joke when one fits; otherwise keep the pun name and translate th ## Check ```bash -node scripts/i18n-check.js # must say: 0 missing, 0 unused, 0 broken -npm test # includes tests/i18n.test.js +node scripts/i18n-check.js # en.js: 0 problems; each language: 0 missing, 0 unused, 0 broken +npm test # includes tests/i18n.test.js (every screen in every language) and the shipped page ``` diff --git a/.claude/skills/write-tests/SKILL.md b/.claude/skills/write-tests/SKILL.md index b465835..efe406c 100644 --- a/.claude/skills/write-tests/SKILL.md +++ b/.claude/skills/write-tests/SKILL.md @@ -37,6 +37,9 @@ pull requests collide. Run one file with `npm test -- tests/route-servers.test.j ## Rules +- **Text in assertions:** match what the player sees (`/Ready in about 3 days/`), or compare with + `ev("tr('pnis.ready_in_about_n_days',{n:3})")`. Tests run the source page, where labels are readable; + the shipped page (ids instead of labels) is covered by `tests/pages.test.js`. - **Deterministic.** Never rely on luck. Use the default seed, `window.__reseed(n)`, or set state directly (`S.day=…`, `S.ev.x=…`). - **Force a specific random failure or event** by patching the picker: diff --git a/CLAUDE.md b/CLAUDE.md index ea30581..bf2ab35 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -54,9 +54,10 @@ npm run perf -- --base-ref origin/main --browser # the same, also in real Chro a real pun, or keep the plain word. - **Easter eggs stay secret.** Never mention hidden jokes or easter eggs (for example whatever `elephant()` does) in commit messages, release notes or the CHANGELOG. -- **Every player-facing string is translated.** Wrap it in `tr()`, `trn()` or `N_()` - and add every translation (`site/i18n/*.js`) in the same change with `scripts/i18n-add.js` - (see `add-strings`). +- **Every player-facing string is translated, by label.** Code uses `tr('area.label')`, + `trn('area.label', n)` or `N_('area.label')` (anything stored in a save: `N_()`), never English text. + Add the English (`src/i18n/en.js`) and every translation (`site/i18n/*.js`) in the same change with + `scripts/i18n-add.js` (see `add-strings`). - **Phones first.** About 70% of players are on phones. Every new panel, button and modal must work at 360 px wide, in portrait and landscape, using the phone tab bar and bottom sheets. Check `isPhone()` layouts, not just desktop. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3dcf1d7..d5d7f23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,8 +41,10 @@ Many people work on the game at once. A few habits keep your pull request from c New files in `src/` and `tests/` are picked up automatically; nothing needs registering. - Add actions to the matching file in `src/game/90-actions/`, not wherever there is room. - Lists (cities, cables, networks) take one entry per line; keep id-keyed tables sorted. -- Add translations with `node scripts/i18n-add.js` rather than by hand: it keeps the dictionaries - sorted, so your new strings don't land on the same lines as everyone else's. +- Text is keyed by labels (`tr('pnis.ready_in_about_n_days')`, English in `src/i18n/en.js`). Add new + text with `node scripts/i18n-add.js` rather than by hand: it writes the English and the translations + and keeps every dictionary sorted, so your new strings don't land on the same lines as everyone + else's. Fixing English wording no longer touches the translations. - The `CHANGELOG.md` bullet is the one place everybody writes. If it conflicts, keep both bullets. ### Your branch still edits `site/index.html`? @@ -58,8 +60,9 @@ git status # fix any conflict it lists, then npm test && git commit ``` -It splits your version of the page and the one you started from the same way `src/` was made, merges -each piece into `src/`, and applies your dictionary changes entry by entry. It only reports conflicts +It splits your version of the page and the one you started from the same way `src/` was made (your +English text becomes labels too), merges each piece into `src/`, and applies your English and +dictionary changes entry by entry. It only reports conflicts where your change and `main` touched the same lines. ## Pull requests @@ -97,8 +100,9 @@ where your change and `main` touched the same lines. ## Translations Every player-facing string goes through `tr()`, `trn()` or `N_()`. Dictionaries live -in `site/i18n/` (English text → translation, one entry per line, sorted). To add a language, copy -`it.js`, translate the values, register the language in the language list in `src/index.html`, and run +in `site/i18n/` (label → translation, one entry per line, sorted; the English for each label is in +`src/i18n/en.js`). To add a language, copy `it.js`, translate the values (`en.js` lists the same labels +in the same order), register the language in the language list in `src/index.html`, and run `node scripts/i18n-check.js ` until it reports nothing missing, unused or broken. The CI job "translations" runs the same check on every pull request, shows each language's coverage in the run summary, and also fails if a new language is not added to the language list or to the offline cache in `site/sw.js`. Language pull requests must be reviewed by a human who speaks the language, and diff --git a/README.md b/README.md index e64a010..e54b792 100644 --- a/README.md +++ b/README.md @@ -61,10 +61,11 @@ npm run i18n:check # lists text missing from (or stale in) the translations ``` src/ the game page, in pieces (joined into one index.html at build) index.html the shell: , static markup, @include lines + i18n/en.js English for every label, inlined into the page styles/ CSS game/ the game script, by topic: world, networks, simulation, actions, UI, map… site/ static files, deployed as they are - i18n/it.js Italian translation, loaded only when the game runs in Italian + i18n/it.js Italian translation (label → text), loaded only when the game runs in Italian i18n/pt.js Portuguese (Brazil) translation, loaded only when the game runs in Portuguese i18n/fr.js French translation, loaded only when the game runs in French images/og-image.png social preview (1200×630) @@ -80,14 +81,13 @@ docs/ architecture and decisions (docs/adr/) ## Translations -English is the source text. Player-facing strings in `src/` go through -`tr('Unlocks at level {n}.', {n})` (or `trn(one, other, n)` for plurals); static markup -uses `data-i18n`, and `aria-label`/`title` are translated at boot. Each language is a -`site/i18n/.js` file mapping the English text to its translation, plus an entry in -`SOT_LANGS` (the language loader in `src/index.html`). Missing entries fall back to -English, so new English text never breaks the game; `npm run i18n:check` lists what -needs translating, and the tests make sure every translation keeps its `{placeholders}` -and HTML tags. +Player-facing text is keyed by label, and English is a dictionary like the others. Code says +`tr('pnis.ready_in_about_n_days', {n})` (or `trn('save.n_pop', n)` for plurals); static markup uses +`data-i18n="label"`. The English is in `src/i18n/en.js`, inlined into the page; each other language is +a `site/i18n/.js` file mapping the same labels to its text, plus an entry in `SOT_LANGS` (the +language loader in `src/index.html`). Missing translations fall back to English, so new text never +breaks the game; `npm run i18n:check` lists what needs translating, and the tests make sure every +translation keeps its `{placeholders}`, HTML tags and plural forms. ## Releasing diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 39af49d..15ca65b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -7,7 +7,8 @@ the build joins them into **one self-contained `index.html`** (one inline `, static markup, the language loader, two @include lines + index.html shell: , static markup, the language loader, the @include lines + i18n/en.js the English for every label → inlined at the top of the page's "); + assert.ok(labels.has('pnis.ok_label') && labels.has('pnis.kept')); + assert.ok(problems.some((p) => p.includes('pnis.foo_bar') && p.includes('N_()')), 'a bare label'); + assert.ok(problems.some((p) => p.includes('not a label')), 'English text where a label belongs'); +}); diff --git a/tests/pages.test.js b/tests/pages.test.js index 1f5616c..3d0a74b 100644 --- a/tests/pages.test.js +++ b/tests/pages.test.js @@ -70,3 +70,19 @@ test('pages: only the release workflow deploys, and only with the GitHub Pages a assert.match(rel, /actions\/deploy-pages@/); assert.match(rel, /path: \.\/_site/); }); + +test('pages: the shipped page and dictionaries, with labels shrunk to ids, still say the right things', () => { + const { load } = require('./harness'); + const file = path.join(OUT, 'index.html'), dir = path.join(OUT, 'i18n'); + assert.doesNotMatch(read('index.html'), /tr\('pnis\.delivery/, 'labels are shrunk in the shipped page'); + for (const [lang, word] of [['en', 'Customers'], ['it', 'Clienti'], ['fr', null]]) { + const { ev, errors } = load(lang === 'en' ? { file } : { file, lang, dir }); + ev("ACT.start({});S.cash=1e8;ACT.launchBB({city:'fra'});for(let i=0;i<40;i++)dayTick();ACT.leftTab({t:'noc'});renderAll()"); + const text = ev("['hud','leftBody','panelBody','modalCard','toasts'].map(i=>document.getElementById(i)?.textContent||'').join(' ')"); + if (word) assert.ok(text.includes(word), `${lang}: ${word}`); + assert.doesNotMatch(text, /\b[a-z_]+\.[a-z0-9_]{6,}\b/, `${lang}: no raw labels`); + assert.equal(ev("tr(FLOOD_WHO[0])"), ev("tr('failures.a_botnet_of_40_000_smart')"), `${lang}: labels kept for saves still translate`); + assert.notEqual(ev("tr(FLOOD_WHO[0])"), 'failures.a_botnet_of_40_000_smart'); + assert.deepEqual(errors, []); + } +});