feat(i18n): blocking key-completeness gate — every locale carries every en.json key (#13827)

New blocking gate `i18n:check-keys` (`scripts/i18n/check-key-completeness.mjs`): every locale catalog must carry exactly the key set of `en.json`, whatever the age of the key. The percentage and new-key gates let batch 1 (#13044) ship 43 keys short and batch 2 (#13660) 10 keys short. Wired into the i18n-ui-coverage job; documented in QUALITY_GATES.md and the i18n guide (post-merge re-sync, retranslation with pinned names).

⚠️ base-red inherited: #12732

scripts/i18n/check-key-completeness.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * OmniRoute — i18n key COMPLETENESS gate (CI gate, blocking).
+ *
+ * Every `src/i18n/messages/<locale>.json` must carry exactly the key set of `en.json`:
+ * no leaf absent, no leaf the source no longer has. A `__MISSING__:` placeholder counts as
+ * present (the ratio gate judges its content); an ABSENT key is the defect this gate names.
+ *
+ * Why the two sibling gates cannot see it (the incident it encodes, 2026-09-15):
+ *   - `check-ui-keys-coverage.mjs` enforces an 80 % floor per locale — 43 absent keys out of
+ *     ~13,000 still reads 99.7 %.
+ *   - `check-new-key-coverage.mjs` judges only the keys a PR ADDS to en.json. A locale batch
+ *     is generated from the en.json of the moment the branch is cut; while its translation
+ *     runs for days the base keeps adding keys, and the batch PR adds none itself — so the
+ *     nine batch-1 catalogs (#13044) landed 43 keys short and the eight batch-2 catalogs
+ *     (#13660) 10 keys short. The home widget test was the first thing that noticed.
+ *
+ * This gate is absolute, not diff-based: it compares the tree as it is.
+ *
+ * Usage:
+ *   node scripts/i18n/check-key-completeness.mjs            # blocking
+ *   node scripts/i18n/check-key-completeness.mjs --warn     # report only, exit 0
+ *   npm run i18n:check-keys
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(SCRIPT_DIR, "..", "..");
+const MESSAGES_DIR = path.join(ROOT, "src", "i18n", "messages");
+const SOURCE_LOCALE = "en";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Dotted leaf paths of a catalog tree (objects recurse, everything else is a leaf). */
+export function leafPaths(node, prefix = "", out = new Set()) {
+  if (!isPlainObject(node)) return out;
+  for (const [key, value] of Object.entries(node)) {
+    const dotted = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(value)) leafPaths(value, dotted, out);
+    else out.add(dotted);
+  }
+  return out;
+}
+
+/**
+ * Pure core. `en` is the source catalog, `locales` maps locale code → catalog. Returns one
+ * entry per locale whose key set differs from the source, sorted by locale, with sorted
+ * `missing` (in en, absent in the locale) and `extra` (in the locale, gone from en) lists.
+ * Locales with an identical key set are not listed.
+ */
+export function findIncompleteLocales({ en, locales }) {
+  const source = leafPaths(en);
+  const gaps = [];
+  for (const locale of Object.keys(locales).sort()) {
+    const target = leafPaths(locales[locale]);
+    const missing = [...source].filter((k) => !target.has(k)).sort();
+    const extra = [...target].filter((k) => !source.has(k)).sort();
+    if (missing.length || extra.length) gaps.push({ locale, missing, extra });
+  }
+  return gaps;
+}
+
+async function readCatalogs() {
+  const files = (await fs.readdir(MESSAGES_DIR)).filter((f) => f.endsWith(".json")).sort();
+  const locales = {};
+  let en = null;
+  for (const file of files) {
+    const code = file.slice(0, -".json".length);
+    const parsed = JSON.parse(await fs.readFile(path.join(MESSAGES_DIR, file), "utf8"));
+    if (code === SOURCE_LOCALE) en = parsed;
+    else locales[code] = parsed;
+  }
+  if (!en) throw new Error(`[i18n-keys] ${SOURCE_LOCALE}.json not found in ${MESSAGES_DIR}`);
+  return { en, locales };
+}
+
+function formatReport(gaps, sample = 5) {
+  const lines = [];
+  for (const { locale, missing, extra } of gaps) {
+    const parts = [];
+    if (missing.length) {
+      parts.push(
+        `${missing.length} missing (${missing.slice(0, sample).join(", ")}${missing.length > sample ? ", …" : ""})`
+      );
+    }
+    if (extra.length) {
+      parts.push(
+        `${extra.length} extra (${extra.slice(0, sample).join(", ")}${extra.length > sample ? ", …" : ""})`
+      );
+    }
+    lines.push(`  - ${locale}: ${parts.join("; ")}`);
+  }
+  return lines.join("\n");
+}
+
+async function main() {
+  const warnOnly = process.argv.includes("--warn");
+  const { en, locales } = await readCatalogs();
+  const gaps = findIncompleteLocales({ en, locales });
+  const total = leafPaths(en).size;
+  const count = Object.keys(locales).length;
+  if (gaps.length === 0) {
+    console.log(
+      `[i18n-keys] OK — ${count} locales carry all ${total} keys of en.json, none extra.`
+    );
+    return;
+  }
+  const missingTotal = gaps.reduce((s, g) => s + g.missing.length, 0);
+  const extraTotal = gaps.reduce((s, g) => s + g.extra.length, 0);
+  console.error(
+    `[i18n-keys] ${warnOnly ? "WARN" : "FAIL"} — ${gaps.length}/${count} locales differ from en.json (${missingTotal} missing, ${extraTotal} extra leaves):`
+  );
+  console.error(formatReport(gaps));
+  console.error(
+    "[i18n-keys] Fix: node scripts/i18n/sync-ui-keys.mjs --locale=<codes> --translate-markers (adds the missing keys and translates them); extra keys mean the source dropped them — remove them from the locale."
+  );
+  if (!warnOnly) process.exitCode = 1;
+}
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error(`[i18n-keys] ${err.message}`);
+    process.exitCode = 1;
+  });
+}