Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
#!/usr/bin/env node
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// bento/dash internationalization rig — and the packer that feeds it.
//
// node scripts/test-dash-i18n.ts verify (CI)
// node scripts/test-dash-i18n.ts --write regenerate dash/src/i18n/packed.ts
//
// WHAT THIS PROVES. English-string-as-key is a wonderful authoring choice and a
// terrible one to leave unguarded, because every failure mode is SILENT:
//
// 1. DRIFT KILLS A TRANSLATION WITHOUT A TRACE. The key is the source
// sentence, so re-wording a button in main.ts orphans seven translations
// at once and the UI simply reverts to English. Nothing throws, nothing
// logs. So the key universe is SWEPT FROM THE SOURCE and any catalog key
// that no longer matches a t() call is a failure, not a warning.
// 2. A PLACEHOLDER IS A CONTRACT. "{n} rows" interpolates by NAME. A
// translator who writes "{N} rader" or drops the brace ships a string that
// renders the literal token to a user. Placeholders are compared as SETS,
// both ways: missing in the translation, and invented by it.
// 3. NOT EVERY t() TAKES A LITERAL. help.ts and panels.ts hold their English
// in module consts and translate at RENDER time (the correct shape — a
// t() in a module const freezes at import, before the locale is known).
// A regex sweep cannot see those strings, so they are declared below AND
// the rig fails if a NEW indirect call site appears that is not declared.
// Otherwise the first such string would just quietly never be translated.
// 4. A CATALOG IS DEAD WEIGHT IF IT IS NOT REACHABLE. Coverage is reported
// per locale, and an incomplete core catalog is a build failure: catalogs
// ship INSIDE every saved workbook and cannot be corrected without a
// release, so "we'll finish it later" means shipping a half-Japanese app.
//
// The per-locale files in dash/src/i18n/*.ts are the SOURCE OF TRUTH — that is
// what a translator reviews and what a contributor submits. packed.ts is
// generated: it stores each English key ONCE with translations positional by
// column, because seven plain catalogs store the same English sentence seven
// times and deflate cannot dedupe across its 32KB window.
import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs'
import { join, dirname, relative } from 'node:path'
import { fileURLToPath, pathToFileURL } from 'node:url'
const root = join(dirname(fileURLToPath(import.meta.url)), '..')
const srcDir = join(root, 'dash/src')
const i18nDir = join(srcDir, 'i18n')
const OUT = join(i18nDir, 'packed.ts')
/**
* Locale columns, in order. English is the key, so it is never a column.
*
* DERIVED, BECAUSE THIS FILE IS BOTH THE RIG AND THE GENERATOR. The list used
* to be a hardcoded seven, which meant it DEFINED the set it then went on to
* check — so when `pt` shipped in slides, type and spaces and not here, this
* rig reported "every core catalog is complete" with perfect honesty about
* seven locales, and there was no angle from which it could see the eighth.
* A list that both defines and verifies a set cannot detect that the set is
* wrong. Deriving it makes that unrepresentable rather than merely fixed.
*
* THE SET COMES FROM DISK. Every `*.ts` in `i18n/` except the generated table.
* Adding `pt.ts` is now the whole act of adding Portuguese.
*
* THE ORDER COMES FROM THE EXISTING TABLE, and that is the load-bearing half.
* `packed.ts` is POSITIONAL — each key maps to an array of translations indexed
* by this list — so deriving the order from `readdirSync` would trade one
* silent bug for a worse one: the day the sort order and the generated order
* disagree, every translation shifts by a column, in a file that still looks
* perfectly well-formed. So the previous `PACKED_LOCALES` is read back and
* preserved exactly, and anything new is APPENDED. Column stability stops
* being a rule somebody has to remember and becomes a property of the
* generator.
*/
function deriveLocales(): string[] {
const onDisk = readdirSync(i18nDir)
.filter((f) => f.endsWith('.ts') && f !== 'packed.ts')
.map((f) => f.slice(0, -3))
// The order already committed to, straight out of the generated file.
//
// AN ORDER IT CANNOT ESTABLISH IS A FAILURE, NOT A DEFAULT — and the first
// version of this got that wrong in the one way that matters. It fell back to
// `prior = []` on a table it could not read, from which the order becomes
// `onDisk.sort()`: measured on this branch by breaking only the array's
// syntax and running --write, every one of the eight columns permuted
// (["ja","zh-Hans",…] to ["de","es",…]) and the run printed "all checks
// passed".
//
// That is NOT data corruption and the artifact stays internally consistent —
// --write rewrites the table together with PACKED_LOCALES, and consumers read
// positionally against the list in the same file. What it destroys silently
// is the property this function exists to hold: that regeneration is
// byte-identical when nothing changed. It turns a zero-line diff into a
// 744-line reorder on a green run, and a 744-line reorder is exactly the diff
// a bad translation rides through unread.
//
// `prior = []` is right for NO TABLE AT ALL, which `existsSync` already
// separates. Everything else refuses.
let prior: string[] = []
if (existsSync(OUT)) {
const m = /export const PACKED_LOCALES = (\[[^\]]*\])/.exec(readFileSync(OUT, 'utf8'))
if (!m) {
throw new Error(
'packed.ts exists but has no readable PACKED_LOCALES — refusing to guess the column order. ' +
'RESTORE IT FROM GIT. Deleting it instead does regenerate, but from no prior order, which ' +
're-alphabetises every column — a correct table and a whole-file diff, which is the outcome ' +
'this refusal exists to avoid arriving at by accident.')
}
try { prior = JSON.parse(m[1]) as string[] } catch {
throw new Error(
`packed.ts has a PACKED_LOCALES that is not readable JSON (${m[1].slice(0, 60)}) — ` +
'refusing to guess the column order. Restore it from git; deleting it re-alphabetises ' +
'every column instead of preserving the committed order.')
}
}
const set = new Set(onDisk)
// kept in their committed positions, then the newcomers, sorted only among
// themselves so a multi-locale addition is at least deterministic
return [
...prior.filter((l) => set.has(l)),
...onDisk.filter((l) => !prior.includes(l)).sort(),
]
}
const LOCALES = deriveLocales()
/**
* The set on disk and the set in the table must agree.
*
* This is what catches a HALF-LANDED change, which is the specific hazard of a
* generator that is also a rig: add `pt.ts` and forget `--write`, and the table
* has seven columns while the app believes in eight. It also catches the
* reverse — a column for a catalog somebody deleted. Either way the rig would
* otherwise keep passing, because everything it checks would still be
* internally consistent.
*
* It subsumes the "catalog file not listed in LOCALES" guard the other apps
* carry: that guard detects a state which, here, can no longer occur.
*/
function checkPackedSet(): { ok: boolean; msg: string } {
if (!existsSync(OUT)) return { ok: true, msg: 'no table yet' }
// Unreachable while `deriveLocales` runs first and throws on both of these —
// kept as a cheap belt if the order of operations ever changes, not because
// it is expected to fire.
const m = /export const PACKED_LOCALES = (\[[^\]]*\])/.exec(readFileSync(OUT, 'utf8'))
if (!m) return { ok: false, msg: 'packed.ts has no PACKED_LOCALES to compare against' }
let inTable: string[] = []
try { inTable = JSON.parse(m[1]) as string[] } catch { return { ok: false, msg: 'PACKED_LOCALES is not readable JSON' } }
const missing = LOCALES.filter((l) => !inTable.includes(l))
const extra = inTable.filter((l) => !LOCALES.includes(l))
if (!missing.length && !extra.length) return { ok: true, msg: `${inTable.length} locales, table and disk agree` }
const parts: string[] = []
if (missing.length) parts.push(`${missing.join(', ')} ${missing.length === 1 ? 'has a catalog' : 'have catalogs'} but no column — run --write`)
// Deliberately does NOT say "run --write", unlike every other failure here: a
// column with no catalog file means a catalog was DELETED, and that is a
// column removal somebody should look at rather than regenerate past.
if (extra.length) {
parts.push(`${extra.join(', ')} ${extra.length === 1 ? 'has a column' : 'have columns'} but no catalog file — ` +
'restore the catalog, or delete the column deliberately; this one is not for --write to decide')
}
return { ok: false, msg: parts.join('; ') }
}
/**
* Strings that reach t() through a module const rather than as a literal.
*
* These are NOT a bug — they are the right shape. `const TIPS = ['…']` holds
* raw English and `t(tip)` runs at render time, which is exactly what a
* module-level `t()` must not do. But a regex cannot follow the indirection,
* so each table is named here, keyed by the ARGUMENT EXPRESSION as written at
* the call site. Anything else that reaches t() without a literal fails the
* rig — otherwise the first such string would quietly never be translated.
*
* `pick` says where the English lives inside the parsed literal.
*/
const INDIRECT: Array<{ arg: string; file: string; name: string; pick: 'values' | 'items' | 'tuple1' }> = [
{ arg: 'TYPE_LABEL[tp]', file: 'format.ts', name: 'TYPE_LABEL', pick: 'values' },
{ arg: 'AGG_LABEL[v.fn] ?? String(v.fn)', file: 'pivot.ts', name: 'AGG_LABEL', pick: 'values' },
// The Total picker and the totals menu name each aggregate in words (Sum,
// Average…); the footer cell labels its number with the short form.
{ arg: 'AGG_WORD[a]', file: 'format.ts', name: 'AGG_WORD', pick: 'values' },
{ arg: 'AGG_SHORT[spec]', file: 'format.ts', name: 'AGG_SHORT', pick: 'values' },
// The 3D heading. (The 2D chart's kind button says "Edit" since #815 and
// opens the chart editor, so it has no indirect words of its own.)
{ arg: 'VIZ_TITLE[viz.kind]', file: 'viz3d.ts', name: 'VIZ_TITLE', pick: 'values' },
{ arg: 'VIZ_TITLE[scene.kind]', file: 'viz3d.ts', name: 'VIZ_TITLE', pick: 'values' },
{ arg: 'VIZ_KIND_LABEL[viz.kind]', file: 'viz3d.ts', name: 'VIZ_KIND_LABEL', pick: 'values' },
// Import findings name the type a value could not be read as.
{ arg: 'TYPE_LABEL[inf.type]', file: 'format.ts', name: 'TYPE_LABEL', pick: 'values' },
{ arg: 'TYPE_LABEL[plan.type]', file: 'format.ts', name: 'TYPE_LABEL', pick: 'values' },
// Why an imported workbook's defined name was refused.
{ arg: 'NAME_REFUSED[problem]', file: 'xlsx.ts', name: 'NAME_REFUSED', pick: 'values' },
{ arg: 'SECTION_TITLE[section]', file: 'help.ts', name: 'SECTION_TITLE', pick: 'values' },
{ arg: 'r.label', file: 'help.ts', name: 'LABELS', pick: 'tuple1' }, // helpRows() carries LABELS[…][1]
{ arg: 'tip', file: 'help.ts', name: 'TIPS', pick: 'items' },
// The column header renders the SAME table panels.ts wraps in t(); it used to
// render it raw, so the type chip read "Money" in a Japanese workbook.
{ arg: 'TYPE_LABEL[c.type]', file: 'format.ts', name: 'TYPE_LABEL', pick: 'values' },
// The dataset Cell section shows the column's type READ-ONLY beside the
// cell's appearance — the type boundary made visible, so it has to be
// localized like every other reading of this table.
{ arg: 'TYPE_LABEL[col.type]', file: 'format.ts', name: 'TYPE_LABEL', pick: 'values' },
// …and the "this pattern does nothing" note names the type it is refusing to
// format, so it reads the same table again — a fourth spelling of the same
// indirection rather than a fourth table.
{ arg: 'TYPE_LABEL[type]', file: 'format.ts', name: 'TYPE_LABEL', pick: 'values' },
]
/**
* Calls that LOOK like t() and are not. filter.ts binds a local predicate
* named `t` over its filter tests — `for (const t of tests) if (!t(i))`. It is
* listed rather than special-cased so that renaming it away is visible.
*/
const NOT_I18N: Array<{ file: string; arg: string }> = [
{ file: 'dash/src/filter.ts', arg: 'i' },
]
/**
* Keys deliberately left in English in every locale.
*
* The bar is high on purpose. A spreadsheet's vocabulary is settled in every
* one of these languages — Excel and Sheets shipped it decades ago — so
* "hard to translate" is almost never true and a fresh coinage is worse than
* the boring standard word. What survives here is what is not language at all:
* a key name, a unit, a file extension, a formula sample.
*/
const KEEP_ENGLISH = new Map<string, string>([
['Value * Probability', 'a formula sample shown as an input placeholder — it is code, and it is the column names of the starter workbook'],
['3D', 'the same three characters in every one of these locales'],
])
/**
* Rows whose translation is correctly IDENTICAL to the English.
*
* A translation that echoes its key is nearly always a forgotten row, so the
* rig fails on one — but "nearly always" is not always, and a checker that
* cannot be satisfied honestly gets satisfied dishonestly. The first draft of
* the Spanish catalog came back with "Total" rendered "Totales", a plural
* invented purely to get past this check, which is a worse string than the
* correct one. So the correct ones are listed instead, per locale, and stay
* countable as translated because they are.
*/
const SAME_AS_ENGLISH: Record<string, string[]> = {
es: ['Total', 'Editor', 'General', 'Series'],
fr: ['Auto', 'Date', 'Format', 'Orientation', 'Portrait', 'Source', 'Surface', 'Total', 'Type'],
// Japanese and Simplified-Chinese Excel name a new sheet "Sheet2" too, and a
// name that matches the reader's own Excel is the whole point of the key.
ja: ['OK', 'Sheet{n}'],
'zh-Hans': ['Sheet{n}'],
de: ['Dashboard', 'Format', 'Live', 'Name', 'OK', 'Symbol', 'Text', 'Updates'],
it: ['Dashboard', 'Editor', 'File', 'Formula', 'Max', 'Min', 'OK', 'vs'],
// 'Total' and 'Editor' are the same word in Portuguese; 'OK' and 'vs' are
// borrowed unchanged, as they are in the Italian list above.
pt: ['Editor', 'OK', 'Total', 'vs'],
}
// --- sweeping the source -----------------------------------------------------
function tsFiles(dir: string, out: string[] = []): string[] {
for (const e of readdirSync(dir, { withFileTypes: true })) {
const full = join(dir, e.name)
if (e.isDirectory()) { if (e.name !== 'i18n') tsFiles(full, out); continue }
if (e.name.endsWith('.ts') && e.name !== 'i18n.ts') out.push(full)
}
return out
}
/** Unescape a TS single/double-quoted string body. */
const unquote = (s: string): string =>
s.replace(/\\(u\{([0-9a-fA-F]+)\}|u([0-9a-fA-F]{4})|x([0-9a-fA-F]{2})|n|r|t|['"\\`$]|\r?\n)/g,
(_m, _all, uBrace, u4, x2, ) => {
if (uBrace) return String.fromCodePoint(parseInt(uBrace, 16))
if (u4) return String.fromCharCode(parseInt(u4, 16))
if (x2) return String.fromCharCode(parseInt(x2, 16))
const tail = _m.slice(1)
if (tail === 'n') return '\n'
if (tail === 'r') return '\r'
if (tail === 't') return '\t'
if (/^\r?\n$/.test(tail)) return ''
return tail
})
/**
* Blank out comments, preserving offsets and newlines so line numbers survive.
* A `t()` inside prose is not a call site — help.ts's own warning about module
* consts is written as `a t() in a module const freezes`, and without this the
* rig would demand a translation for it.
*/
function blankComments(src: string): string {
const out = src.split('')
let i = 0, q = ''
while (i < src.length) {
const c = src[i]
if (q) {
if (c === '\\') { i += 2; continue }
if (c === q) q = ''
i++; continue
}
if (c === "'" || c === '"' || c === '`') { q = c; i++; continue }
if (c === '/' && src[i + 1] === '/') {
while (i < src.length && src[i] !== '\n') { out[i] = ' '; i++ }
continue
}
if (c === '/' && src[i + 1] === '*') {
const end = src.indexOf('*/', i + 2)
const stop = end < 0 ? src.length : end + 2
for (; i < stop; i++) if (src[i] !== '\n') out[i] = ' '
continue
}
i++
}
return out.join('')
}
/**
* `t` preceded by anything that is not an identifier char, a dot or a quote.
* The dot rules out `x.t(`; the quote rules out a `t(` inside a string.
*/
const T_CALL = /(^|[^A-Za-z0-9_$.'"`\\])t\(/g
/**
* Read `'a'`, or `'a' + 'b' + …`, starting at `at`. Returns the concatenated
* value, or null if what starts there is not a string literal.
*/
function readLiteralChain(src: string, at: number): string | null {
let i = at, out = ''
for (;;) {
const q = src[i]
if (q !== "'" && q !== '"') return i === at ? null : out
const body = new RegExp(`^((?:\\\\.|[^\\\\${q}])*)`).exec(src.slice(i + 1))![1]
out += unquote(body)
i += 1 + body.length + 1
const join = /^\s*\+\s*/.exec(src.slice(i))
if (!join) return out
i += join[0].length
}
}
/** The argument expression as written, up to the matching close paren. */
function argText(src: string, at: number): string {
let depth = 1, i = at, q = ''
for (; i < src.length; i++) {
const c = src[i]
if (q) { if (c === '\\') i++; else if (c === q) q = ''; continue }
if (c === "'" || c === '"' || c === '`') { q = c; continue }
if (c === '(' || c === '[' || c === '{') depth++
else if (c === ')' || c === ']' || c === '}') { depth--; if (!depth) break }
else if (c === ',' && depth === 1) break // t(key, vars) — the key is arg 1
}
return src.slice(at, i).trim().replace(/\s+/g, ' ')
}
function sweepLiterals(): { keys: Set<string>; indirect: Array<{ where: string; file: string; arg: string }> } {
const keys = new Set<string>()
const indirect: Array<{ where: string; file: string; arg: string }> = []
for (const file of tsFiles(srcDir)) {
const src = blankComments(readFileSync(file, 'utf8'))
const rel = relative(root, file)
let m: RegExpExecArray | null
T_CALL.lastIndex = 0
while ((m = T_CALL.exec(src))) {
const open = m.index + m[0].length
const lead = src.slice(open).match(/^\s*/)![0]
const at = open + lead.length
// A literal, or a CHAIN of literals joined with `+`. The chain matters:
// splash.ts wraps a long sentence as `t('… this file. ' + 'Try opening
// it again…')`, and t() receives the JOINED string. Taking only the
// first piece would have made a key that can never match at runtime —
// a translation that is dead the day it is written, which is the exact
// failure this rig exists to prevent.
const lit = readLiteralChain(src, at)
if (lit !== null) { keys.add(lit); continue }
const line = src.slice(0, m.index).split('\n').length
indirect.push({ where: `${rel}:${line}`, file: rel, arg: argText(src, open) })
}
}
return { keys, indirect }
}
/** Slice a `const NAME … = <literal>` out of a file and evaluate it. */
function readConst(file: string, name: string): unknown {
const src = readFileSync(join(srcDir, file), 'utf8')
const decl = new RegExp(`\\bconst\\s+${name}\\b[^=]*=\\s*`).exec(src)
if (!decl) throw new Error(`${file}: no const ${name}`)
const from = decl.index + decl[0].length
const open = src[from]
const close = open === '{' ? '}' : ']'
if (open !== '{' && open !== '[') throw new Error(`${file}: ${name} is not an object or array literal`)
// Depth scan, skipping string bodies so a brace inside a tip does not close it.
let depth = 0, i = from, q = ''
for (; i < src.length; i++) {
const c = src[i]
if (q) { if (c === '\\') i++; else if (c === q) q = ''; continue }
if (c === "'" || c === '"' || c === '`') { q = c; continue }
if (c === open) depth++
else if (c === close) { depth--; if (!depth) break }
}
const body = src.slice(from, i + 1)
// The literals are plain string data; type annotations live outside the slice.
return Function(`"use strict"; return (${body})`)()
}
function sweepIndirect(): Set<string> {
const keys = new Set<string>()
for (const spec of INDIRECT) {
const v = readConst(spec.file, spec.name) as Record<string, unknown> | unknown[]
const take = (s: unknown) => { if (typeof s === 'string' && s) keys.add(s) }
if (spec.pick === 'values') Object.values(v as Record<string, unknown>).forEach(take)
else if (spec.pick === 'items') (v as unknown[]).forEach(take)
else Object.values(v as Record<string, unknown[]>).forEach((tup) => take(tup[1]))
}
return keys
}
// --- catalogs ----------------------------------------------------------------
/** Read one per-locale catalog by evaluating its exported object literal. */
function readCatalog(code: string): Record<string, string> {
const file = join(i18nDir, `${code}.ts`)
if (!existsSync(file)) return {}
const src = readFileSync(file, 'utf8')
const start = src.indexOf('{', src.indexOf('export const '))
const end = src.lastIndexOf('}')
if (start < 0 || end < 0) return {}
return Function(`"use strict"; return (${src.slice(start, end + 1)})`)() as Record<string, string>
}
/** `{name}` tokens, as a sorted set. `{{x}}` is not a thing in dash. */
function placeholders(s: string): string[] {
return [...new Set([...s.matchAll(/\{([A-Za-z0-9_]+)\}/g)].map((m) => m[1]))].sort()
}
// --- run ---------------------------------------------------------------------
let failures = 0
/** `--keys` prints the swept key universe and nothing else, so it can be piped. */
const QUIET = process.argv.includes('--keys')
const say = (s: string) => { if (!QUIET) console.log(s) }
const fail = (msg: string) => { failures++; say(` FAIL ${msg}`) }
const ok = (msg: string) => say(` ok ${msg}`)
const { keys: literalKeys, indirect: indirectSites } = sweepLiterals()
// (3) an undeclared indirect call site would be a string nobody can translate
const unexplained = indirectSites.filter((s) =>
!INDIRECT.some((spec) => spec.arg === s.arg) &&
!NOT_I18N.some((n) => n.file === s.file && n.arg === s.arg))
if (unexplained.length) {
for (const s of unexplained) fail(`indirect t() at ${s.where} is not declared in INDIRECT: t(${s.arg})`)
} else {
ok(`every indirect t() call site is declared (${indirectSites.length} site(s))`)
}
// …and a declaration nobody calls is a stale table the sweep still pays for
for (const spec of INDIRECT) {
if (!indirectSites.some((s) => s.arg === spec.arg)) {
fail(`INDIRECT declares t(${spec.arg}) for ${spec.file}:${spec.name}, but no such call site exists any more`)
}
}
const indirectKeys = sweepIndirect()
const keys = [...new Set([...literalKeys, ...indirectKeys])].sort()
ok(`swept ${keys.length} strings (${literalKeys.size} literal, ${indirectKeys.size} via module consts)`)
// The swept key universe, for a translator (or a tool) to work from. Printing
// it from the RIG rather than from a second scanner is the point: a key list
// that disagrees with the checker is how a catalog drifts on day one.
if (process.argv.includes('--keys')) {
process.stdout.write(JSON.stringify(keys, null, 1) + '\n')
process.exit(0)
}
const known = new Set(keys)
const catalogs = Object.fromEntries(LOCALES.map((c) => [c, readCatalog(c)])) as Record<string, Record<string, string>>
// (1) drift: a catalog key that matches no source string is a dead translation
for (const loc of LOCALES) {
const dead = Object.keys(catalogs[loc]).filter((k) => !known.has(k))
if (dead.length) {
fail(`${loc}: ${dead.length} catalog key(s) match no t() in the source — the source string was re-worded and these are now dead:`)
for (const k of dead.slice(0, 8)) console.log(` ${JSON.stringify(k)}`)
if (dead.length > 8) console.log(` … and ${dead.length - 8} more`)
}
}
if (!failures) ok('no catalog key has drifted away from its source string')
// (2) placeholders are a contract, checked both ways
let phBad = 0
for (const loc of LOCALES) {
for (const [k, v] of Object.entries(catalogs[loc])) {
if (!known.has(k)) continue
const want = placeholders(k), got = placeholders(v)
const missing = want.filter((p) => !got.includes(p))
const invented = got.filter((p) => !want.includes(p))
if (missing.length) { phBad++; fail(`${loc}: {${missing.join('} {')}} missing from the translation of ${JSON.stringify(k)}`) }
if (invented.length) { phBad++; fail(`${loc}: {${invented.join('} {')}} invented by the translation of ${JSON.stringify(k)}`) }
}
}
if (!phBad) ok('every {placeholder} survives every translation, spelled identically')
// (4) coverage — an incomplete core catalog cannot be fixed without a release
const missingPer: Record<string, string[]> = {}
for (const loc of LOCALES) {
missingPer[loc] = keys.filter((k) => !KEEP_ENGLISH.has(k) && !(typeof catalogs[loc][k] === 'string' && catalogs[loc][k].length))
}
const translatable = keys.filter((k) => !KEEP_ENGLISH.has(k)).length
say(`\n coverage (${translatable} translatable of ${keys.length} swept; ${KEEP_ENGLISH.size} kept English by design)`)
for (const loc of LOCALES) {
const done = translatable - missingPer[loc].length
const pct = translatable ? Math.round((done / translatable) * 1000) / 10 : 100
say(` ${loc.padEnd(8)} ${String(done).padStart(4)}/${translatable} ${String(pct).padStart(5)}%`)
}
say('')
for (const loc of LOCALES) {
if (!missingPer[loc].length) continue
fail(`${loc}: ${missingPer[loc].length} string(s) have no translation — a core catalog ships inside every saved workbook and cannot be patched without a release`)
for (const k of missingPer[loc].slice(0, 6)) console.log(` ${JSON.stringify(k)}`)
}
if (!LOCALES.some((l) => missingPer[l].length)) ok('every core catalog is complete')
// A translation identical to its English key is usually a forgotten row rather
// than a deliberate one — the deliberate ones are named in KEEP_ENGLISH.
const echoes: string[] = []
for (const loc of LOCALES) {
for (const [k, v] of Object.entries(catalogs[loc])) {
if (v !== k || !known.has(k) || KEEP_ENGLISH.has(k)) continue
if (SAME_AS_ENGLISH[loc]?.includes(k)) continue
echoes.push(`${loc}: ${JSON.stringify(k)}`)
}
}
if (echoes.length) {
fail(`${echoes.length} translation(s) are byte-identical to their English key and are declared in neither KEEP_ENGLISH nor SAME_AS_ENGLISH:`)
for (const e of echoes.slice(0, 8)) console.log(` ${e}`)
} else ok('no translation silently echoes its English key')
// …and an allowance nobody uses is a licence left lying around: the day that
// string DOES get a real translation, the entry would quietly excuse a future
// echo of it instead.
const staleAllow: string[] = []
for (const [loc, list] of Object.entries(SAME_AS_ENGLISH)) {
for (const k of list) if (catalogs[loc]?.[k] !== k) staleAllow.push(`${loc}: ${JSON.stringify(k)}`)
}
if (staleAllow.length) {
fail(`${staleAllow.length} SAME_AS_ENGLISH entry(ies) no longer describe the catalog — drop them:`)
for (const e of staleAllow) say(` ${e}`)
} else ok('every SAME_AS_ENGLISH allowance is still earning its place')
// --- the packed table --------------------------------------------------------
const rows = keys.map((k) => {
const row: Array<string | 0> = LOCALES.map((c) => {
const v = catalogs[c][k]
return typeof v === 'string' && v.length ? v : 0
})
while (row.length && row[row.length - 1] === 0) row.pop() // a short row reads as English
return [k, row] as const
})
const body = `// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// GENERATED by scripts/test-dash-i18n.ts — do not edit. Run it after changing
// a catalog or adding a t() string; the rig fails if this is out of date:
//
// node scripts/test-dash-i18n.ts --write
//
// One row per English key: the key is stored ONCE and the translations follow
// by column. \`0\` (or a short row) means "no translation in that locale" and
// falls back to the English key — which is also the source text, so a hole
// degrades to a readable sentence rather than a blank.
/** Column order for every row in PACKED. */
export const PACKED_LOCALES = ${JSON.stringify(LOCALES)} as const
/** English source string -> translations, positional by PACKED_LOCALES. */
export const PACKED: Record<string, ReadonlyArray<string | 0>> = {
${rows.map(([k, r]) => ` ${JSON.stringify(k)}: ${JSON.stringify(r)},`).join('\n')}
}
`
const current = existsSync(OUT) ? readFileSync(OUT, 'utf8') : null
if (process.argv.includes('--write')) {
writeFileSync(OUT, body)
say(`\n wrote ${relative(root, OUT)} — ${keys.length} strings × ${LOCALES.length} locales`)
} else if (current !== body) {
fail(`dash/src/i18n/packed.ts is out of date — run: node scripts/test-dash-i18n.ts --write`)
} else {
ok('packed.ts matches the per-locale catalogs')
}
// The SET check, distinct from the CONTENT check above. `--write` regenerates
// the table from whatever catalogs exist, so the content comparison can be
// perfectly green over a table that is simply missing a locale — which is what
// shipped: seven columns, an eighth catalog nowhere, and every check passing.
{
const r = checkPackedSet()
if (r.ok) ok(`PACKED_LOCALES covers every catalog on disk (${r.msg})`)
else fail(`packed.ts and dash/src/i18n/ disagree about which locales exist — ${r.msg}`)
}
// --- the wiring, actually run ------------------------------------------------
//
// Everything above reads FILES. This part boots the real facade — the same
// module the app imports — against a stubbed localStorage and navigator, and
// asks it questions. A catalog can be perfect and still never reach a user if
// registration or locale resolution is wrong, and that failure is invisible to
// any amount of static checking: the app just quietly speaks English.
//
// The stubs are deliberately minimal. kernel/src/storage.ts exists because
// reading `localStorage` THROWS in an opaque origin, so it must degrade to
// "unset" rather than crash; giving it a working Map here keeps that path out
// of the way of what is being measured.
const lsStore = new Map<string, string>()
Object.defineProperty(globalThis, 'localStorage', {
configurable: true,
value: {
getItem: (k: string) => (lsStore.has(k) ? lsStore.get(k)! : null),
setItem: (k: string, v: string) => { lsStore.set(k, String(v)) },
removeItem: (k: string) => { lsStore.delete(k) },
},
})
const setNav = (language: string) =>
Object.defineProperty(globalThis, 'navigator', { configurable: true, value: { language } })
const facade = pathToFileURL(join(srcDir, 'i18n.ts')).href
let bust = 0
/** Boot the facade fresh under a given navigator.language. */
async function boot(language: string) {
setNav(language)
lsStore.clear()
// A new query string re-evaluates the facade, whose registerI18n() clears
// the kernel's memoized locale — which is the only way to re-resolve.
return (await import(`${facade}?boot=${bust++}`)) as {
t: (en: string, vars?: Record<string, string | number>) => string
locale: () => string
setLocale: (c: string) => void
}
}
setNav('en')
const probe = ['Save', 'Workbook', 'Pivot', 'Grand total']
// Resolution, including the two ways a full tag has to reach a column: the
// kernel's base-language fallback (fr-CA -> fr) and this app's zh aliases,
// without which a Taiwanese reader lands on English with zh-Hant right there.
const RESOLVE: Array<[string, string]> = [
['en-GB', 'en'], ['ja-JP', 'ja'], ['fr-CA', 'fr'], ['de-AT', 'de'],
['it-CH', 'it'], ['es-MX', 'es'],
['zh-CN', 'zh-Hans'], ['zh-SG', 'zh-Hans'], ['zh', 'zh-Hans'],
['zh-TW', 'zh-Hant'], ['zh-HK', 'zh-Hant'], ['zh-MO', 'zh-Hant'],
// Was ['pt-BR', 'en'] with the comment "dash carries no pt: it must degrade,
// not guess" — a correct assertion about a real absence, which then had to be
// read every time as a statement about what dash SHOULD do. It carries pt now.
['pt-BR', 'pt'],
['pt', 'pt'],
['xx-YY', 'en'],
]
let resolveBad = 0
for (const [nav, want] of RESOLVE) {
const m = await boot(nav)
// The active code may be the tag itself (an alias column) — compare by what
// it actually SPEAKS, which is the only thing a reader can tell apart.
const spoken = probe.map((k) => m.t(k)).join('|')
const expected = want === 'en' ? probe.join('|') : probe.map((k) => catalogs[want][k] ?? k).join('|')
if (spoken !== expected) { resolveBad++; fail(`navigator.language "${nav}" should speak ${want} — got ${JSON.stringify(spoken)}`) }
}
if (!resolveBad) ok(`every navigator.language reaches the right catalog (${RESOLVE.length} tags, incl. the zh aliases)`)
{
const m = await boot('ja-JP')
const k = '{n} of {all} rows'
const got = m.t(k, { n: 3, all: 9 })
if (got === k || /\{n\}|\{all\}/.test(got)) fail(`interpolation into a TRANSLATED string is broken: ${JSON.stringify(got)}`)
else ok(`{placeholder} interpolation survives translation (ja: ${JSON.stringify(got)})`)
const miss = 'a string that is in no catalog anywhere'
if (m.t(miss) !== miss) fail('an untranslated key must fall back to its English self')
else ok('an unknown key falls back to the English source string')
m.setLocale('x-pseudo')
const ps = m.t('Save')
if (!/^⟦.*⟧$/.test(ps)) fail(`setLocale('x-pseudo') is not reachable — the audit locale is how unswept strings are found (got ${JSON.stringify(ps)})`)
else ok(`setLocale('x-pseudo') wraps every swept string (Save -> ${ps})`)
m.setLocale('de')
if (m.t('Save') !== catalogs['de']['Save']) fail('the About picker path (setLocale) does not switch catalogs')
else ok('setLocale switches catalogs, as the About picker needs')
}
console.log(failures ? `\n${failures} FAILURE(S)` : '\ndash i18n: all checks passed')
process.exit(failures ? 1 : 0)