refactor(i18n): key messages by English text; add Russian

Replace the semantic keys with the English source text, so code reads as the
UI does and English needs no catalog: t('Save keys'), tn(count, one, other)
for plurals, msg() for text stored in data, and bare data-i18n* markup that
translates the element's own English. Other languages are one flat JSON each.

- Simplify src/i18n: drop namespaces, the configurable locale pair
  (GEV_DEFAULT_LOCALE / GEV_SECONDARY_LOCALE) and its build defines. Locale
  comes from ?lang=, the stored choice, then browser languages.
- Add scripts/i18n.mjs (npm run i18n): extracts every message from t/tn/msg
  and markup, and fails on missing, unused, placeholder-mismatched or
  wrongly-shaped plural entries. npm test runs it via catalog.test.mjs.
- Add Russian (src/i18n/locales/ru.json, 833 messages), started from the
  community catalog in #312 and reviewed against the current English.
- Fix data-i18n placed on parents that would wipe their children (cockpit
  LEVEL and local weather cells, first-run EXPLORE MANUALLY tile), and a
  doubled degree sign in the TRACK ACQUIRED signal.
- Rewrite docs/TRANSLATORS.md for the new workflow; drop sections the earlier
  merge resurrected in docs/CURRENT-STATE.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
German KhokhlovandClaude Opus 5.5 committed 2026-10-12 13:48:56 +04:00
1 parent dfbaeafbd8
commit 13efd411b6
112 files changed
+4419 -4856

No files matched your search

+257
View File
@@ -0,0 +1,257 @@
// Keeps the locale catalogs in step with the code.
//
// npm run i18n check every catalog (also run by npm test)
// npm run i18n -- --prune also drop entries the code no longer uses
// npm run i18n -- --missing ru print what ru lacks, as JSON to translate
//
// Messages are the English literals passed to t(), tn() and msg() in src/,
// plus the markup opted in with data-i18n* in src/ui/templates and index.html.
import { readFileSync, writeFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const LOCALES_DIR = path.join(ROOT, 'src/i18n/locales');
const STRING = String.raw`'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|\`(?:\\.|[^\`\\$])*\``;
const CALL = new RegExp(
String.raw`\b(t|msg)\(\s*(${STRING})|\btn\(\s*[^,]+?,\s*(${STRING})\s*,\s*(${STRING})`,
'g',
);
function unquote(literal) {
const body = literal.slice(1, -1);
return body.replace(
/\\(u\{[0-9a-fA-F]+\}|u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|.)/gs,
(_, esc) => {
if (esc[0] === 'u' || esc[0] === 'x') {
return String.fromCodePoint(parseInt(esc.replace(/[ux{}]/g, ''), 16));
}
return { n: '\n', t: '\t', r: '\r' }[esc] ?? esc;
},
);
}
const ENTITIES = {
amp: '&',
lt: '<',
gt: '>',
quot: '"',
apos: "'",
nbsp: ' ',
};
function decodeHtml(text) {
return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (all, name) => {
if (name[0] === '#') {
const hex = name[1] === 'x' || name[1] === 'X';
return String.fromCodePoint(
parseInt(name.slice(hex ? 2 : 1), hex ? 16 : 10),
);
}
return ENTITIES[name.toLowerCase()] ?? all;
});
}
const normalize = (text) => text.replace(/\s+/g, ' ').trim();
function trackedFiles(...pathspecs) {
return execFileSync(
'git',
[
'ls-files',
'--cached',
'--others',
'--exclude-standard',
'--',
...pathspecs,
],
{
cwd: ROOT,
encoding: 'utf8',
},
)
.split('\n')
.filter(Boolean);
}
/**
* Every message the code can ask for.
* @returns {Map<string, {plural: boolean, one?: string, where: string}>}
*/
export function extractMessages() {
const messages = new Map();
const add = (text, where, plural = null) => {
if (!text) return;
const known = messages.get(text);
if (known && Boolean(known.plural) !== Boolean(plural)) {
throw new Error(
`${where}: "${text}" is used both as plural and plain text (also ${known.where})`,
);
}
if (!known)
messages.set(text, { plural: Boolean(plural), one: plural?.one, where });
};
const sources = trackedFiles(
'src/*.js',
'src/*.mjs',
'src/**/*.js',
'src/**/*.mjs',
).filter(
(file) =>
!file.startsWith('src/i18n/') &&
!/\.test\.mjs$|\/testSupport\//.test(file),
);
for (const file of sources) {
const source = readFileSync(path.join(ROOT, file), 'utf8');
for (const match of source.matchAll(CALL)) {
const line = source.slice(0, match.index).split('\n').length;
const where = `${file}:${line}`;
if (match[2]) {
if (match[2][0] === '`' && match[2].includes('${')) continue;
add(unquote(match[2]), where);
} else {
add(unquote(match[4]), where, { one: unquote(match[3]) });
}
}
}
const markup = trackedFiles('index.html', 'src/ui/templates/*.html');
const TAG = /<([a-zA-Z][\w-]*)(\s[^>]*?)\/?>([^<]*)/gs;
for (const file of markup) {
const html = readFileSync(path.join(ROOT, file), 'utf8');
for (const [, tag, attrs, text] of html.matchAll(TAG)) {
const where = `${file} <${tag}>`;
if (/\sdata-i18n(\s|=|$)/.test(attrs))
add(normalize(decodeHtml(text)), where);
for (const [, name] of attrs.matchAll(
/\sdata-i18n-(title|aria-label|placeholder)\b/g,
)) {
const value = attrs.match(new RegExp(String.raw`\s${name}="([^"]*)"`));
if (value) add(decodeHtml(value[1]), where);
else
throw new Error(
`${where}: data-i18n-${name} without a ${name} attribute`,
);
}
}
}
return messages;
}
const placeholders = (text) =>
[...String(text).matchAll(/\{([A-Za-z0-9_]+)\}/g)]
.map((m) => m[1])
.sort()
.join(',');
export function catalogPath(locale) {
return path.join(LOCALES_DIR, `${locale}.json`);
}
export function readCatalog(locale) {
return JSON.parse(readFileSync(catalogPath(locale), 'utf8'));
}
export function shippedLocales() {
return trackedFiles('src/i18n/locales/*.json').map((file) =>
path.basename(file, '.json'),
);
}
/**
* Compare one catalog with the extracted messages.
* @returns {{missing: string[], stale: string[], errors: string[]}}
*/
export function checkCatalog(locale, catalog, messages) {
const categories = new Intl.PluralRules(locale).resolvedOptions()
.pluralCategories;
const missing = [];
const errors = [];
for (const [text, info] of messages) {
if (!Object.hasOwn(catalog, text)) {
missing.push(text);
continue;
}
const entry = catalog[text];
if (info.plural) {
if (!entry || typeof entry !== 'object') {
errors.push(`"${text}" needs plural forms ${categories.join('/')}`);
continue;
}
for (const category of categories) {
if (typeof entry[category] !== 'string')
errors.push(`"${text}" lacks the "${category}" form`);
else if (placeholders(entry[category]) !== placeholders(text))
errors.push(
`"${text}" [${category}] placeholders differ: ${entry[category]}`,
);
}
} else if (typeof entry !== 'string') {
errors.push(`"${text}" must be a string`);
} else if (placeholders(entry) !== placeholders(text)) {
errors.push(`"${text}" placeholders differ: ${entry}`);
}
}
const stale = Object.keys(catalog).filter((text) => !messages.has(text));
return { missing, stale, errors };
}
function main(args) {
const messages = extractMessages();
const missingFor = args.includes('--missing')
? args[args.indexOf('--missing') + 1]
: null;
if (missingFor) {
const catalog = readCatalog(missingFor);
const out = {};
for (const text of checkCatalog(missingFor, catalog, messages).missing) {
const info = messages.get(text);
out[text] = info.plural ? { one: info.one, other: text } : '';
}
console.log(JSON.stringify(out, null, 2));
return 0;
}
let failed = false;
for (const locale of shippedLocales()) {
let catalog = readCatalog(locale);
const { missing, stale, errors } = checkCatalog(locale, catalog, messages);
if (args.includes('--prune') && stale.length) {
catalog = Object.fromEntries(
Object.entries(catalog).filter(([text]) => messages.has(text)),
);
writeFileSync(
catalogPath(locale),
`${JSON.stringify(catalog, null, 2)}\n`,
);
console.log(`${locale}: pruned ${stale.length} unused entries`);
} else if (stale.length) {
failed = true;
console.log(
`${locale}: ${stale.length} entries the code no longer uses (npm run i18n -- --prune):`,
);
for (const text of stale) console.log(` ${JSON.stringify(text)}`);
}
if (missing.length) {
failed = true;
console.log(
`${locale}: ${missing.length} missing (npm run i18n -- --missing ${locale}):`,
);
for (const text of missing)
console.log(` ${JSON.stringify(text)} ${messages.get(text).where}`);
}
for (const error of errors) {
failed = true;
console.log(`${locale}: ${error}`);
}
if (!missing.length && !stale.length && !errors.length) {
console.log(`${locale}: ${messages.size} messages, complete`);
}
}
return failed ? 1 : 0;
}
if (process.argv[1] === fileURLToPath(import.meta.url)) {
process.exitCode = main(process.argv.slice(2));
}
+31 -124
View File
@@ -421,10 +421,7 @@
"src/localRequestGate.mjs",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -448,10 +445,7 @@
"src/data/layerSnapshot.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -465,10 +459,7 @@
"src/app/stateChannel.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -482,10 +473,7 @@
"src/ui/radioTunerModel.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -501,10 +489,7 @@
"src/ui/cctvPresentation.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -525,10 +510,7 @@
"src/ui/panelRailGeometry.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -559,10 +541,7 @@
"src/ui/panelRailGeometry.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -574,10 +553,7 @@
"src/ui/scenePresentation.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -719,10 +695,7 @@
"src/data/cameraArrival.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -831,10 +804,7 @@
"src/data/cameraArrival.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -891,10 +861,7 @@
"src/data/modelEligibility.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -936,10 +903,7 @@
"src/data/modelEligibility.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -995,10 +959,7 @@
"src/data/inputOwnership.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -1047,10 +1008,7 @@
"src/data/inputOwnership.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -1079,10 +1037,7 @@
"src/data/inputOwnership.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium", "satellite.js"]
},
@@ -1112,10 +1067,7 @@
"src/data/inputOwnership.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -1153,10 +1105,7 @@
"src/data/infrastructureOverlayEntry.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium", "@mapbox/vector-tile", "pbf"]
},
@@ -1186,10 +1135,7 @@
"src/ui/panelRailGeometry.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -1233,10 +1179,7 @@
"src/layers/traffic/roadModes.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium", "pbf", "@mapbox/vector-tile"]
},
@@ -1262,10 +1205,7 @@
"src/data/cameraSensitivity.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -1309,10 +1249,7 @@
"src/layers/cctv/sourcePolicy.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["hls.js", "cesium"]
},
@@ -1410,10 +1347,7 @@
"src/data/inputOwnership.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -1433,10 +1367,7 @@
"src/data/inputOwnership.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -1488,10 +1419,7 @@
"src/maps/imageryHost.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -1541,10 +1469,7 @@
"src/voice/pointerReticle.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -2351,10 +2276,7 @@
"src/app/embed.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": [
"hls.js",
@@ -2879,10 +2801,7 @@
"src/sources/infrastructureData.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": [
"hls.js",
@@ -2987,10 +2906,7 @@
"src/ui/uiLifetime.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -3021,10 +2937,7 @@
"src/ui/visualSettings.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": ["cesium"]
},
@@ -3047,10 +2960,7 @@
"src/ui/uiLifetime.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},
@@ -3176,10 +3086,7 @@
"src/voice/pointerReticle.js",
"src/i18n/index.js",
"src/i18n/locale.js",
"src/i18n/locales/en/cockpit.js",
"src/i18n/locales/en/layers.js",
"src/i18n/locales/en/setup.js",
"src/i18n/locales/en/shell.js"
"src/i18n/locales/ru.json"
],
"external": []
},