platform/scripts/i18n/scan-hardcoded.ts

#!/usr/bin/env bun
/**
 * Counts candidate hardcoded user-facing strings in the web UI.
 *
 * Two jobs. It sizes the localization work (docs/localization.md quotes its output), and once an area
 * reaches zero it becomes the guard that stops the debt coming back — see ZEROED below.
 *
 * It is a heuristic and it is deliberately a FLOOR. It cannot see multi-line JSX text, ternaries
 * inside JSX, strings passed down as props, or anything a plugin renders. A falling number means
 * progress; a zero means "nothing this scanner can see", not "nothing left".
 *
 *   bun scripts/i18n/scan-hardcoded.ts            # summary by area
 *   bun scripts/i18n/scan-hardcoded.ts --files    # worst files first
 *   bun scripts/i18n/scan-hardcoded.ts --list ui.button   # print the strings themselves
 *   bun scripts/i18n/scan-hardcoded.ts --check    # non-zero exit if a zeroed area regressed
 */
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';

const AREAS = [
  { label: 'officer-web (shell)', root: 'src/apps/officer-web' },
  { label: 'officerdev (panels)', root: 'src/workspaces/officerdev/src' },
  { label: 'shared components', root: 'src/workspaces/components' },
] as const;

/**
 * Areas that have been converted and must stay converted. Add an area here the moment it reaches
 * zero — enabling every area on day one would just be red for weeks and get ignored.
 *
 * 'shared components' landed 2026-08-23 (localization phase 1). It holds three `new Error()` messages
 * that must NEVER be translated; they are reported but excluded from the check, which is why the
 * neverTranslate split below has to exist for this entry to be possible at all.
 *
 * 'officer-web (shell)' landed 2026-08-23 (phase 2). It holds no never-translate hits of its own; what it
 * does hold is ~30 `<Untranslated reason="foreign-ui-label">` labels quoted from Google's console, which
 * `stripUntranslated` skips for the same reason.
 *
 * 'officerdev (panels)' landed 2026-08-23 (phase 3). It holds nine `new Error()` messages for whoever is
 * reading a terminal, not a user — same never-translate shape as 'shared components'. Two more strings
 * are marked `i18n-exempt` rather than never-translate: `useTaskRunner.ts`'s "Running:"/"Error:" framing
 * is interleaved with raw stdout/stderr inside one monospace `<pre>` feed, so translating the frame alone
 * would read as broken mid-buffer — the same reasoning as the never-translate list, reached by a
 * different mechanism because it's not a thrown Error.
 */
const ZEROED: string[] = ['shared components', 'officer-web (shell)', 'officerdev (panels)'];

const SKIP = /node_modules|\.gen\.|[/\\]locales[/\\]|[/\\]vendor[/\\]|\.test\.|\.d\.ts$/;

// A quoted literal, single or double. Kept as two groups because JS has no branch reset.
const Q = String.raw`(?:"([^"\n]{2,120})"|'([^'\n]{2,120})')`;

/**
 * `neverTranslate` marks a category the doc's "What must never be translated" list forbids converting —
 * so it is reported (an agent should see it and confirm), but excluded from `--check`.
 *
 * Without that split the guard is unusable: an area holding one legitimate `new Error()` can never
 * reach zero, so it could never be added to ZEROED, so the debt guard could never be switched on for
 * it. Counting work that must NOT be done against a target of zero makes the target unreachable.
 */
const PATTERNS: { kind: string; rx: RegExp; neverTranslate?: true }[] = [
  // >Some visible words<
  //
  // The lookbehind rejects `=>`, so an arrow return type does not read as JSX text: `(id: string) =>
  // Promise<unknown>` was reported as the string "Promise".
  { kind: 'jsx text', rx: /(?<!=)>\s*([A-Z][A-Za-z0-9][^<>{}\n]{2,100}?)\s*</g },
  // placeholder="..." and friends
  {
    kind: 'attributes',
    rx: new RegExp(
      String.raw`\b(?:placeholder|title|aria-label|alt|label|description|tooltip|emptyMessage)\s*=\s*` + Q,
      'g',
    ),
  },
  { kind: 'toast/alert', rx: new RegExp(String.raw`\b(?:toast(?:\.\w+)?|alert|confirm)\s*\(\s*` + Q, 'g') },
  // label: 'Status' — nav items, menus, table columns. The largest hidden category.
  {
    kind: 'object labels',
    rx: new RegExp(
      String.raw`\b(?:label|name|title|heading|placeholder|description|tooltip|emptyText)\s*:\s*` + Q,
      'g',
    ),
  },
  // Thrown Errors are for whoever is reading a terminal at 4am. They stay in one language.
  //
  // Matches a template literal as well as a quoted one: `new Error(\`Whisper returned ${res.status}\`)`
  // was falling through to `template str` and so counted as convertible, which is the opposite of true.
  {
    kind: 'thrown errors',
    rx: new RegExp(String.raw`new Error\(\s*(?:` + Q + String.raw`|\`([^\`]{2,120})\`)`, 'g'),
    neverTranslate: true,
  },
  // `Failed to create ${kind}` — needs interpolation, so it costs more to convert.
  //
  // The lookbehind hands a thrown Error to the category above instead of counting it here as well: a
  // string matched by two patterns is counted twice, and it stayed convertible, so the area could never
  // reach zero however it was treated.
  { kind: 'template str', rx: /(?<!new Error\()`([A-Z][^`\n]{4,100}\$\{[^`]*)`/g },
];

/** Filters out ids, class names, paths, mime types and SCREAMING_CONSTANTS. */
function isHuman(value: string | undefined): value is string {
  if (!value) return false;
  const s = value.trim();
  if (s.length < 3) return false;
  if (!/[A-Za-z]{3}/.test(s)) return false;
  if (/^[a-z0-9\-_./:]+$/.test(s)) return false;
  if (/^(https?:|\/|#|data:|application\/|image\/)/.test(s)) return false;
  // Allows . and - so credential-format examples like `GOCSPX-...` fall under the same rule.
  if (/^[A-Z0-9_.-]+$/.test(s)) return false;
  // A namespaced storage or channel key: an ALL-CAPS prefix, then a separator, then an interpolation —
  // `FULLSCREEN_PANEL:${workspace.key}`. The SCREAMING_CONSTANT rule above misses it because the
  // interpolated half is lowercase.
  if (/^[A-Z0-9_]{3,}[.:/-]/.test(s)) return false;
  // `Bearer ${token}` is an Authorization header value, not a sentence. Caught by the template-string
  // pattern because it starts with a capital and interpolates; excluded here because an auth scheme
  // followed by a credential is never something a person reads.
  if (/^(Bearer|Basic|Token|Digest)\s/.test(s)) return false;
  // A single token carrying digits AND punctuation is a name, not a sentence — the OCR section's
  // placeholder is the example model file `Qwen2.5-VL-7B-Instruct-q4_k_m.gguf`. Prose has spaces; the
  // whitespace test is what keeps this from eating real one-word labels, which never look like this.
  if (!/\s/.test(s) && /\d/.test(s) && /[-_.]/.test(s)) return false;
  // Tailwind, reached via a `description:`/`label:` key in a classNames object — e.g. sonner's
  // `description: 'group-[.toast]:text-muted-foreground'`.
  //
  // The test is per TOKEN, not on the whole string: every space-separated token must look like a
  // utility (all lowercase, no sentence punctuation) and at least one must carry a variant colon or
  // an arbitrary-value bracket. Testing the whole string instead cost a real label — "Application
  // type:" was filtered because it ends in a colon, which is also how prose introduces a value.
  const tokens = s.split(/\s+/);
  const utilityish = (tok: string) => /^[a-z0-9:_\-[\]().#&/%!]+$/.test(tok);
  if (tokens.every(utilityish) && tokens.some((tok) => /[:[]/.test(tok))) return false;
  return true;
}

/**
 * Commented-out code is not user-facing text. `Header.tsx` carries a disabled dev-console button inside
 * a `{/* … *\/}` block, and counting it means the area can never reach zero without editing a comment.
 *
 * Deliberately only two shapes, both unambiguous: a block comment, and a line whose first non-space
 * characters are `//`. Stripping every `//` would eat the tail of any string holding a URL.
 */
const stripComments = (source: string): string =>
  source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '');

/**
 * `<code>`, `<kbd>`, `<pre>` and `<samp>` mark content as code rather than prose — that is what the
 * elements are for. `<code>Authorization: Bearer …</code>` is an HTTP header, which the doc's
 * never-translate list covers as an identifier crossing a boundary, and translating it would break the
 * thing it documents.
 */
const stripCodeElements = (source: string): string =>
  source.replace(/<(code|kbd|pre|samp)\b[^>]*>[\s\S]*?<\/\1>/g, '<$1/>');

/**
 * An explicit, per-line opt-out: `// i18n-exempt: <reason>` exempts the NEXT line.
 *
 * For the cases no syntactic rule can reach — chiefly a prompt written for a model rather than a
 * reader. `<Untranslated>` covers JSX; this covers the rest, and the two together mean the scanner does
 * not need another heuristic every time a new shape of never-translate string turns up.
 *
 * A reason is mandatory: the regex will not match a bare `// i18n-exempt`. That is the whole safeguard —
 * somebody has to write down why, and `grep -rn "i18n-exempt"` lists every one for review.
 */
const stripExemptLines = (source: string): string => {
  const lines = source.split('\n');
  return lines.map((line, i) => (/\/\/\s*i18n-exempt:\s*\S/.test(lines[i - 1] ?? '') ? '' : line)).join('\n');
};

/**
 * `<Untranslated reason="…">` marks text that must stay in one language — today, a label quoted from
 * another product's UI, which docs/localization.md classifies as an identifier.
 *
 * Skipped for the same reason `neverTranslate` categories are excluded from `--check`: counting work the
 * doc FORBIDS doing against a target of zero makes the target unreachable. The marker is explicit and
 * carries a reason, so this cannot become a quiet catch-all — unlike a heuristic, somebody has to write
 * it and say why.
 */
const stripUntranslated = (source: string): string =>
  source.replace(/<Untranslated\b[^>]*>[\s\S]*?<\/Untranslated>/g, '<Untranslated/>');

function* walk(dir: string): Generator<string> {
  let entries: string[];
  try {
    entries = readdirSync(dir);
  } catch {
    return;
  }
  for (const entry of entries) {
    const path = join(dir, entry);
    if (SKIP.test(path)) continue;
    let isDir = false;
    try {
      isDir = statSync(path).isDirectory();
    } catch {
      continue;
    }
    if (isDir) yield* walk(path);
    else if (path.endsWith('.tsx') || path.endsWith('.ts')) yield path;
  }
}

type Hit = { kind: string; value: string; file: string };

function scan(root: string): { files: number; hits: Hit[] } {
  const hits: Hit[] = [];
  let files = 0;

  for (const file of walk(root)) {
    files++;
    let source: string;
    try {
      // Exempt lines go FIRST: stripComments would remove the marker they depend on.
      source = stripUntranslated(stripCodeElements(stripComments(stripExemptLines(readFileSync(file, 'utf8')))));
    } catch {
      continue;
    }
    for (const { kind, rx } of PATTERNS) {
      rx.lastIndex = 0;
      for (const match of source.matchAll(rx)) {
        const value = match.slice(1).find((group) => group !== undefined);
        if (isHuman(value)) hits.push({ kind, value: value.trim(), file });
      }
    }
  }
  return { files, hits };
}

const args = new Set(process.argv.slice(2));
const listPrefix = process.argv.includes('--list') ? process.argv[process.argv.indexOf('--list') + 1] : undefined;

const results = AREAS.map((area) => ({ ...area, ...scan(area.root) }));
const kinds = PATTERNS.map((p) => p.kind);
const pad = (s: string | number, n: number) => String(s).padStart(n);

console.log(
  `${'area'.padEnd(22)} ${pad('files', 5)} ${kinds.map((k) => pad(k.slice(0, 13), 14)).join('')} ${pad('total', 7)}`,
);
for (const r of results) {
  const byKind = kinds.map((k) => pad(r.hits.filter((h) => h.kind === k).length, 14)).join('');
  console.log(`${r.label.padEnd(22)} ${pad(r.files, 5)} ${byKind} ${pad(r.hits.length, 7)}`);
}

const all = results.flatMap((r) => r.hits);
const distinct = new Set(all.map((h) => h.value));
const interpolated = new Set(all.filter((h) => h.kind === 'template str').map((h) => h.value));

const NEVER_KINDS = new Set(PATTERNS.filter((p) => p.neverTranslate).map((p) => p.kind));
const convertible = (hits: Hit[]) => hits.filter((h) => !NEVER_KINDS.has(h.kind));

console.log(
  `${'TOTAL'.padEnd(22)} ${pad(
    results.reduce((n, r) => n + r.files, 0),
    5,
  )} ${kinds.map((k) => pad(all.filter((h) => h.kind === k).length, 14)).join('')} ${pad(all.length, 7)}`,
);
console.log();
console.log(`occurrences        ${all.length}`);
console.log(`  convertible      ${convertible(all).length}`);
console.log(`  never-translate  ${all.length - convertible(all).length}  (${[...NEVER_KINDS].join(', ')})`);
console.log(`distinct strings   ${distinct.size}`);
console.log(`  needing params   ${interpolated.size}`);

if (args.has('--files')) {
  console.log('\nworst files:');
  const perFile = new Map<string, number>();
  for (const h of all) perFile.set(h.file, (perFile.get(h.file) ?? 0) + 1);
  for (const [file, n] of [...perFile].sort((a, b) => b[1] - a[1]).slice(0, 25)) {
    console.log(`  ${pad(n, 4)}  ${file}`);
  }
}

if (listPrefix) {
  console.log(`\nstrings in files matching "${listPrefix}":`);
  for (const h of all.filter((x) => x.file.includes(listPrefix))) console.log(`  [${h.kind}] ${h.value}`);
}

if (args.has('--check')) {
  const regressed = results
    .filter((r) => ZEROED.includes(r.label))
    .map((r) => ({ label: r.label, hits: convertible(r.hits) }))
    .filter((r) => r.hits.length > 0);
  if (regressed.length > 0) {
    console.error('\nThese areas were converted and have regressed:');
    for (const r of regressed) {
      console.error(`  ${r.label}: ${r.hits.length} hardcoded strings`);
      for (const h of r.hits) console.error(`    [${h.kind}] ${h.value}  — ${h.file}`);
    }
    console.error('\nUse a catalog key. See docs/localization.md.');
    process.exit(1);
  }
  console.log(`\ncheck: ok (${ZEROED.length} area(s) held at zero)`);
}