Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

9.1 KB
Raw Blame
import fs from "node:fs";
import path from "node:path";
import ts from "typescript";

function listCodeFiles(dir) {
  const out = [];
  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
    if (ent.name === "node_modules" || ent.name === ".next") continue;
    const full = path.join(dir, ent.name);
    if (ent.isDirectory()) out.push(...listCodeFiles(full));
    else if (ent.isFile() && /\.tsx?$/.test(ent.name)) out.push(full);
  }
  return out;
}

function toRel(p, root) {
  return path.relative(root, p).replaceAll("\\", "/");
}

function hasUiText(s) {
  // Very rough heuristic: letters / CJK / common punctuation sequences
  return /[A-Za-z\u4e00-\u9fff]/.test(s);
}

function auditFile(content, file) {
  const findings = [];
  const source = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
  const attrs = new Set(["title", "placeholder", "alt", "aria-label"]);
  function add(kind, raw) {
    const text = raw.replace(/\s+/g, " ").trim();
    if (text.length > 1 && hasUiText(text) && text !== "DeepTutor") {
      findings.push({ kind, text });
    }
  }
  function visit(node) {
    if (ts.isJsxText(node)) add("jsxText", node.text);
    if (ts.isJsxAttribute(node) && attrs.has(node.name.getText(source))) {
      if (node.initializer && ts.isStringLiteral(node.initializer)) {
        add(`attr:${node.name.getText(source)}`, node.initializer.text);
      }
    }
    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) &&
        ["alert", "confirm"].includes(node.expression.text)) {
      for (const text of literalKeys(node.arguments[0])) add(`${node.expression.text}()`, text);
    }
    ts.forEachChild(node, visit);
  }
  visit(source);
  return findings;
}

const webRoot = path.resolve(process.cwd());
const targets = ["app", "components", "features", "hooks", "lib", "shared"]
  .map((dir) => path.join(webRoot, dir))
  .filter((dir) => fs.existsSync(dir));

const strict = process.argv.includes("--strict");
const fileFilterIdx = process.argv.indexOf("--file");
const fileFilter =
  fileFilterIdx >= 0 ? String(process.argv[fileFilterIdx + 1] || "").trim() : "";
const showAll = process.argv.includes("--show-all");

/** Parse literal keys without mistaking comments, escapes or plural keys for gaps. */
function literalKeys(expression) {
  if (!expression) return [];
  if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) {
    return [expression.text];
  }
  if (ts.isConditionalExpression(expression)) {
    return [...literalKeys(expression.whenTrue), ...literalKeys(expression.whenFalse)];
  }
  return [];
}

function translationKeys(file, content) {
  const source = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
  const keys = new Set();
  function visit(node) {
    if (ts.isCallExpression(node)) {
      const callee = node.expression;
      const isTranslation =
        (ts.isIdentifier(callee) && callee.text === "t") ||
        (ts.isPropertyAccessExpression(callee) && callee.name.text === "t");
      if (isTranslation) {
        for (const key of literalKeys(node.arguments[0])) keys.add(key);
      }
    }
    ts.forEachChild(node, visit);
  }
  visit(source);
  return keys;
}

const REQUIRED_LOCALES = ["en", "zh", "fr", "de", "uk"];
// French and Ukrainian are deliberately partial. i18next falls back to the
// English resource per key; these floors make a coverage regression visible.
const MIN_USED_COVERAGE = new Map([
  ["fr", 0.65],
  ["uk", 0.75],
]);

function hasTranslation(entries, pluralForms, key) {
  if (Object.hasOwn(entries, key)) return true;
  return pluralForms.every((form) => Object.hasOwn(entries, `${key}_${form}`));
}

function placeholders(value) {
  if (typeof value !== "string") return new Set();
  return new Set([...value.matchAll(/\{\{\s*([^{}]+?)\s*\}\}/g)].map((match) => match[1].trim()));
}

function placeholderMismatches(english, localized) {
  const mismatches = [];
  for (const [key, translation] of Object.entries(localized)) {
    if (!Object.hasOwn(english, key)) continue;
    const expected = placeholders(english[key]);
    const actual = placeholders(translation);
    const missing = [...expected].filter((name) => !actual.has(name));
    const extra = [...actual].filter(
      (name) => !expected.has(name) && !(name === "count" && /_(zero|one|two|few|many|other)$/.test(key)),
    );
    if (missing.length || extra.length) mismatches.push({ key, missing, extra });
  }
  return mismatches;
}

function reportUntranslatedKeys() {
  const localeDir = path.join(webRoot, "locales");
  if (!fs.existsSync(localeDir)) {
    console.error("[i18n:audit] Missing locales directory");
    process.exitCode = 1;
    return;
  }
  const locales = new Set(REQUIRED_LOCALES);
  for (const ent of fs.readdirSync(localeDir, { withFileTypes: true })) {
    if (ent.isDirectory() && !ent.name.startsWith(".")) locales.add(ent.name);
  }

  const known = new Map();
  for (const locale of locales) {
    const file = path.join(localeDir, locale, "app.json");
    if (!fs.existsSync(file)) {
      console.error(`[i18n:audit] Missing ${locale}/app.json`);
      process.exitCode = 1;
      continue;
    }
    known.set(locale, JSON.parse(fs.readFileSync(file, "utf8")));
  }
  const english = known.get("en");
  if (!english) return;

  const usedKeys = new Set();
  const roots = ["app", "components", "features", "hooks", "lib", "shared"]
    .map((dir) => path.join(webRoot, dir))
    .filter((dir) => fs.existsSync(dir));
  for (const dir of roots) {
    for (const file of listCodeFiles(dir)) {
      const content = fs.readFileSync(file, "utf8");
      for (const key of translationKeys(file, content)) {
        if (key) usedKeys.add(key);
      }
    }
  }

  const englishKeys = new Set(Object.keys(english));
  for (const [locale, entries] of known) {
    const pluralForms = new Intl.PluralRules(locale).resolvedOptions().pluralCategories;
    const missing = [...usedKeys].filter((key) => !hasTranslation(entries, pluralForms, key));
    const translated = usedKeys.size - missing.length;
    const usedCoverage = usedKeys.size ? translated / usedKeys.size : 1;
    const catalogTranslated = [...englishKeys].filter((key) => Object.hasOwn(entries, key)).length;
    const catalogCoverage =
      englishKeys.size
        ? catalogTranslated / englishKeys.size
        : 1;
    const formatPercent = (ratio) => `${(ratio * 100).toFixed(1)}%`;
    const floor = MIN_USED_COVERAGE.get(locale);

    if (floor === undefined) {
      console.log(`[i18n:audit] ${locale}: ${translated}/${usedKeys.size} used keys (${formatPercent(usedCoverage)}), strict`);
      if (missing.length) {
        console.error(`[i18n:audit] ${locale}: ${missing.length} t() literals lack a locale entry`);
        process.exitCode = 1;
      }
    } else {
      console.log(
        `[i18n:audit] ${locale}: ${translated}/${usedKeys.size} used keys (${formatPercent(usedCoverage)}); ` +
          `${catalogTranslated}/${englishKeys.size} English catalog keys (${formatPercent(catalogCoverage)}); ` +
          `${missing.length} used keys fall back to English ` +
          `(minimum ${formatPercent(floor)} used coverage)`,
      );
      if (usedCoverage < floor) {
        console.error(`[i18n:audit] ${locale}: used-key coverage below ${formatPercent(floor)}`);
        process.exitCode = 1;
      }
    }

    if (process.argv.includes("--show-missing") && missing.length) {
      console.log(`\n- ${locale} missing used keys`);
      for (const key of missing.sort()) console.log(`  - ${JSON.stringify(key)}`);
    }
    if (locale === "en") continue;
    const mismatches = placeholderMismatches(english, entries);
    if (mismatches.length) {
      process.exitCode = 1;
      console.error(`[i18n:audit] ${locale}: ${mismatches.length} interpolation placeholder mismatches`);
      for (const { key, missing: lost, extra } of mismatches.slice(0, 20)) {
        console.error(`  ${JSON.stringify(key)}: missing [${lost.join(", ")}], extra [${extra.join(", ")}]`);
      }
    }
  }
}

reportUntranslatedKeys();

const allFindings = [];
for (const dir of targets) {
  const files = listCodeFiles(dir);
  for (const f of files) {
    if (fileFilter && !toRel(f, webRoot).includes(fileFilter)) continue;
    const content = fs.readFileSync(f, "utf8");
    const findings = auditFile(content, f);
    if (findings.length) {
      allFindings.push({
        file: toRel(f, webRoot),
        findings,
      });
    }
  }
}

if (!allFindings.length) {
  console.log("[i18n:audit] OK (no obvious UI literals found)");
  process.exit(process.exitCode || 0);
}

console.log(`[i18n:audit] Found ${allFindings.length} files with potential UI literals`);
const fileLimit = showAll ? allFindings.length : 80;
for (const item of allFindings.slice(0, fileLimit)) {
  console.log(`\n- ${item.file}`);
  const perFileLimit = showAll ? item.findings.length : 10;
  for (const f of item.findings.slice(0, perFileLimit)) {
    console.log(`  - ${f.kind}: ${JSON.stringify(f.text)}`);
  }
  if (!showAll && item.findings.length > 10)
    console.log(`  - ... +${item.findings.length - 10} more`);
}
if (!showAll && allFindings.length > 80)
  console.log(`\n... and ${allFindings.length - 80} more files`);

if (strict) process.exit(1);
process.exit(process.exitCode || 0);