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

@ -0,0 +1,52 @@
// Shrinks labels for the shipped page (docs/adr/0003-translations-by-label.md, "Performance").
//
// In src/ a label is readable: tr('pnis.delivery_2_to_6_weeks'). Shipped like that, every label would
// sit in the page twice (in the code and as a key in the inlined English), about 20% more page after
// compression. So the build gives each label a short id ('a', 'b', … '2kq'), in the code, in the
// static markup, in the inlined English and in every translation file, and the page ends up about the
// size it was when the English text itself was the key.
//
// Labels passed to N_() are kept whole: those are the ones the game stores (in saves, in the inbox log)
// and shows later, and an id would mean something else in the next release.
const { CALL } = require('../legacy/labels');
const D = require('./dict');
const LABEL = /^[a-z0-9_]+(\.[a-z0-9_]+)+$/;
const EN_OPEN = '(window.I18N=window.I18N||{}).en={';
// {map: label → id for every label that gets one, kept: labels that stay whole}.
function plan(html, en) {
const kept = new Set();
for (const m of html.matchAll(CALL)) if (m[1] === 'N_') kept.add(m[2].slice(1, -1));
const map = new Map();
let n = 0;
for (const l of Object.keys(en).sort(D.cmp)) if (!kept.has(l)) map.set(l, (n++).toString(36));
return { map, kept };
}
const rekey = (dict, map) => Object.fromEntries(Object.entries(dict).map(([k, v]) => [map.get(k) || k, v]));
// The page and the dictionaries with short ids. `dicts` is {lang: dict} for the translations.
function compile(html, en, dicts) {
const { map } = plan(html, en);
// English: the inlined dictionary, swapped whole.
const a = html.indexOf(EN_OPEN), b = html.indexOf('\n};\n', a);
if (a < 0 || b < 0) throw new Error('compile-labels: the inlined English dictionary is missing from the page');
const head = html.lastIndexOf('\n', a) + 1;
let out = html.slice(0, head) + D.format('en', '', rekey(en, map)) + html.slice(b + 4);
// Code: the first argument of tr() and trn(); N_() keeps its label.
out = out.replace(CALL, (m, fn, lit) => {
if (fn === 'N_') return m;
const l = lit.slice(1, -1);
return map.has(l) ? m.replace(lit, `'${map.get(l)}'`) : m;
});
// Static markup.
out = out.replace(/ data-i18n(-aria-label|-title)?="([^"]+)"/g, (m, attr, l) => (map.has(l) ? ` data-i18n${attr || ''}="${map.get(l)}"` : m));
const left = [...out.matchAll(/(?<![\w$.])(tr|trn)\(\s*'([^']*)'/g)].map((m) => m[2]).filter((l) => LABEL.test(l) && !map.has(l) && !(l in en));
if (left.length) throw new Error(`compile-labels: labels with no English: ${[...new Set(left)].slice(0, 5).join(', ')}`);
const compiled = {};
for (const [lang, d] of Object.entries(dicts)) compiled[lang] = rekey(d, map);
return { html: out, dicts: compiled, map };
}
module.exports = { compile, plan };

View file

@ -3,8 +3,9 @@
// The result is the same single, self-contained index.html the game has always shipped: one request,
// no module loader, no runtime cost. See docs/ARCHITECTURE.md ("Source layout") and docs/adr/.
//
// node scripts/lib/page.js [-o FILE] assemble this checkout (stdout by default)
// node scripts/lib/page.js --ref origin/main -o FILE assemble the page as it is at a git ref
// node scripts/lib/page.js [-o FILE] the page as it ships (stdout by default)
// node scripts/lib/page.js --source [-o FILE] assembled only, labels as in src/ (what tests and npm run dev use)
// node scripts/lib/page.js --ref origin/main -o FILE the page as it ships at a git ref
//
// --ref uses that commit's own assembler, so it keeps working when this file changes; refs from before
// the split (when the page was site/index.html) are read as they are.
@ -85,18 +86,25 @@ function assembleRef(ref, cwd = ROOT) {
} finally { fs.rmSync(tmp, { recursive: true, force: true }); }
}
// The assembled page written to a file, for tools that need a path (perf in a real browser, base vs head).
// The page as it ships: assembled, with labels shrunk to short ids (compile-labels.js). Not version-stamped.
// `dicts` ({lang: label-keyed dictionary}) come back with the same ids.
function shipped(dicts = {}) {
const D = require('./dict');
return require('./compile-labels').compile(assemble().html, D.read('en').dict, dicts);
}
// The shipped page written to a file, for tools that need a path (perf in a real browser, base vs head).
function pageFile(file = path.join(os.tmpdir(), `tubes-page-${process.pid}.html`)) {
fs.writeFileSync(file, assemble().html);
fs.writeFileSync(file, shipped().html);
return file;
}
module.exports = { assemble, assembleRef, pageFile, locate, listFiles, ROOT };
module.exports = { assemble, assembleRef, shipped, pageFile, locate, listFiles, ROOT };
if (require.main === module) {
const args = process.argv.slice(2);
const opt = (k) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : null; };
const html = opt('--ref') ? assembleRef(opt('--ref')) : assemble().html;
const html = opt('--ref') ? assembleRef(opt('--ref')) : args.includes('--source') ? assemble().html : shipped().html;
const out = opt('-o');
if (out) { fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true }); fs.writeFileSync(out, html); }
else process.stdout.write(html);