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
76 lines
4 KiB
Markdown
76 lines
4 KiB
Markdown
---
|
|
name: add-strings
|
|
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
|
|
|
|
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('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 (`<b>`, `<br>`, `<small>`) and `{placeholders}` identical in every language.
|
|
- Don't build sentences from translated fragments; translate whole sentences.
|
|
|
|
## Naming a label
|
|
|
|
`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'
|
|
{
|
|
"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 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/
|
|
```
|
|
|
|
- **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
|
|
|
|
Natural, friendly Italian, informal "tu". Keep networking terms that Italian engineers
|
|
use in English (peering, transit, router, POP, PNI, LAG, dark fiber). Translate puns
|
|
into an Italian joke when one fits; otherwise keep the pun name and translate the rest.
|
|
|
|
## Check
|
|
|
|
```bash
|
|
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
|
|
```
|