kandev/apps/web/scripts/i18n-parity.mjs

#!/usr/bin/env node
/**
 * Report translation-catalog parity: how many `en` keys each real locale is
 * missing, and which keys it still carries that `en` no longer defines.
 *
 * WHY THIS EXISTS
 *
 * Real-locale parity is deliberately advisory (#2272): Chinese is maintained by
 * a third party and must never be able to fail our builds. That decision stands.
 * Its cost is that drift is silent — pt-PT shipped complete and then fell 1,791
 * keys behind, an entire absent namespace among them, without any check going
 * red. The measurement existed only as a snippet people pasted into chat logs,
 * which is the same as not existing. This makes it a command.
 *
 * It is a REPORT, NOT A GATE. It exits 0 whatever it finds, and it is wired into
 * neither CI, nor pre-commit, nor `i18n:check`. Making it fail a build would
 * quietly overturn #2272. The one exception is input it cannot read (a malformed
 * catalog throws and exits non-zero) — the same line `i18n-sweep.mjs` draws,
 * because an unparseable file is a broken input, not a finding.
 *
 * Locales and namespaces are both discovered from disk via the same helpers
 * `check-i18n-keys.mjs` uses, so the two can never disagree about what a locale
 * is. Adding `fr/` tomorrow extends the report with no edit here; a hardcoded
 * list is the exact shape that let the last gap hide.
 *
 * WHAT A CLEAN RUN DOES *NOT* TELL YOU
 *
 * 1. It counts MISSING KEYS ONLY. A key whose English text changed after it was
 *    translated still counts as present, so the locale looks complete while the
 *    translation says something the source no longer says. Stale translations are
 *    invisible to this script and no check in this repo detects them today.
 * 2. It measures PRESENCE, NOT QUALITY. Every key can be present and every one of
 *    them wrong, machine-translated, or in the wrong regional variant, and this
 *    prints a clean table. The pseudo-locale (Settings > General > Appearance)
 *    and human review remain the only checks on whether the copy is any good.
 *
 * One deliberate difference from `check-i18n-keys.mjs`: there, a wholly-absent
 * namespace scores as a single advisory issue. Here it counts as every key it
 * would have contained. That difference is the whole point — 889 absent keys
 * reported as "1" is precisely how an entire missing namespace stayed invisible.
 *
 * Usage: node scripts/i18n-parity.mjs [localesDir]
 */
import path from "node:path";

import { discoverRealLocales, readLocaleNamespaces } from "./lib/i18n-catalogs.mjs";

const DEFAULT_LOCALES_DIR = path.join(import.meta.dirname, "..", "src", "locales");
const LOCALES_DIR = process.argv[2] ?? DEFAULT_LOCALES_DIR;

const SOURCE_LOCALE = "en";

/**
 * Per-namespace counts for one locale.
 *
 * `missing` treats an absent namespace file as all of its `en` keys missing —
 * see the note above on why this deliberately diverges from the advisory check.
 */
function localeReport(sourceNamespaces, translatedNamespaces) {
  const missingByNamespace = new Map();
  const extraKeys = [];
  const absentNamespaces = [];

  for (const [namespace, sourceMessages] of sourceNamespaces) {
    const translatedMessages = translatedNamespaces.get(namespace);
    if (!translatedMessages) {
      missingByNamespace.set(namespace, sourceMessages.size);
      absentNamespaces.push(namespace);
      continue;
    }
    let missing = 0;
    for (const key of sourceMessages.keys()) if (!translatedMessages.has(key)) missing += 1;
    missingByNamespace.set(namespace, missing);
    for (const key of translatedMessages.keys()) {
      if (!sourceMessages.has(key)) extraKeys.push(`${namespace}: ${key}`);
    }
  }

  // A namespace the locale has and `en` does not is extra in its entirety.
  const extraNamespaces = [...translatedNamespaces.keys()].filter(
    (ns) => !sourceNamespaces.has(ns),
  );

  return { missingByNamespace, extraKeys, extraNamespaces, absentNamespaces };
}

function pad(value, width, align = "right") {
  const text = String(value);
  return align === "right" ? text.padStart(width) : text.padEnd(width);
}

function renderTable(sourceNamespaces, locales, reports) {
  const namespaces = [...sourceNamespaces.keys()];
  const rowLabel = (ns) => `${ns}.json`;

  const nameWidth = Math.max("namespace".length, ...namespaces.map((ns) => rowLabel(ns).length), 5);
  const columnWidth = (locale, values) =>
    Math.max(locale.length, ...values.map((v) => String(v).length), 4) + 2;

  const sourceTotal = namespaces.reduce((sum, ns) => sum + sourceNamespaces.get(ns).size, 0);
  const sourceValues = [...namespaces.map((ns) => sourceNamespaces.get(ns).size), sourceTotal];
  const sourceWidth = columnWidth(SOURCE_LOCALE, sourceValues);

  const localeTotals = locales.map((locale) =>
    namespaces.reduce((sum, ns) => sum + reports.get(locale).missingByNamespace.get(ns), 0),
  );
  const localeWidths = locales.map((locale, index) =>
    columnWidth(locale, [
      ...namespaces.map((ns) => reports.get(locale).missingByNamespace.get(ns)),
      localeTotals[index],
    ]),
  );

  const lines = [];
  lines.push(
    pad("namespace", nameWidth, "left") +
      pad(SOURCE_LOCALE, sourceWidth) +
      locales.map((locale, i) => pad(locale, localeWidths[i])).join(""),
  );

  const ruleWidth = nameWidth + sourceWidth + localeWidths.reduce((a, b) => a + b, 0);
  const rule = "-".repeat(ruleWidth);
  lines.push(rule);

  for (const ns of namespaces) {
    lines.push(
      pad(rowLabel(ns), nameWidth, "left") +
        pad(sourceNamespaces.get(ns).size, sourceWidth) +
        locales
          .map((locale, i) => pad(reports.get(locale).missingByNamespace.get(ns), localeWidths[i]))
          .join(""),
    );
  }

  lines.push(rule);
  lines.push(
    pad("TOTAL", nameWidth, "left") +
      pad(sourceTotal, sourceWidth) +
      localeTotals.map((total, i) => pad(total, localeWidths[i])).join(""),
  );
  return lines.join("\n");
}

const sourceNamespaces = readLocaleNamespaces(LOCALES_DIR, SOURCE_LOCALE);
const locales = discoverRealLocales(LOCALES_DIR);
const reports = new Map(
  locales.map((locale) => [
    locale,
    localeReport(sourceNamespaces, readLocaleNamespaces(LOCALES_DIR, locale)),
  ]),
);

// Say what was measured over, always. A tool that reports "0 missing" without
// naming its denominator is indistinguishable from one that scanned nothing.
const sourceKeyCount = [...sourceNamespaces.values()].reduce((sum, m) => sum + m.size, 0);
console.log(
  `scanned ${sourceNamespaces.size} namespace(s) / ${sourceKeyCount} ${SOURCE_LOCALE} key(s) ` +
    `across ${locales.length} locale(s) from ${LOCALES_DIR}`,
);

if (sourceNamespaces.size === 0) {
  console.log(`\nNo ${SOURCE_LOCALE} catalog found — nothing to compare against.`);
} else if (locales.length === 0) {
  console.log(`\nNo real locales found (${SOURCE_LOCALE} and pseudo are excluded).`);
} else {
  console.log(`\nMISSING KEYS — the ${SOURCE_LOCALE} column is the denominator, not a finding.\n`);
  console.log(renderTable(sourceNamespaces, locales, reports));

  const absent = locales.flatMap((locale) =>
    reports.get(locale).absentNamespaces.map((ns) => `${locale} / ${ns}: namespace file absent`),
  );
  if (absent.length) {
    console.log(`\nABSENT NAMESPACES — counted above as every key they would hold.\n`);
    for (const line of absent) console.log(`  ${line}`);
  }

  const extras = locales.flatMap((locale) => [
    ...reports.get(locale).extraNamespaces.map((ns) => `${locale} / ${ns}: whole namespace`),
    ...reports.get(locale).extraKeys.map((entry) => `${locale} / ${entry}`),
  ]);
  console.log(
    `\nEXTRA KEYS — present in the locale, absent from ${SOURCE_LOCALE}; ` +
      `a rename or deletion nobody propagated.\n`,
  );
  if (extras.length) {
    for (const line of extras) console.log(`  ${line}`);
    console.log(`\n  ${extras.length} extra entr(ies).`);
  } else {
    console.log("  (none)");
  }
}

// Advisory by design — see the header. Never exit non-zero on a finding.
process.exit(0);