@json-translate/check 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @json-translate/check
+
+Small CI-friendly validator for JSON locale files.
+
+It compares translated locale files against a source JSON file and fails when:
+
+- target JSON cannot be parsed
+- keys are missing
+- unexpected keys were added
+- placeholders drift between source and target strings
+
+```bash
+npx @json-translate/check --source locales/en.json --target locales/fr.json --target locales/de.json
+```
+
+Example GitHub Actions step:
+
+```yaml
+- name: Check translated JSON locales
+  run: npx @json-translate/check --source locales/en.json --target locales/fr.json,locales/de.json
+```
+
+For the translation step itself, use JSON Translate:
+https://www.json-translate.com/?utm_source=cli&utm_medium=devtool&utm_campaign=json_translate_check

package/bin/json-translate-check.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const usage = `json-translate-check
+
+Validate translated JSON locale files against a source file.
+
+Usage:
+  json-translate-check --source locales/en.json --target locales/fr.json --target locales/de.json
+  json-translate-check -s locales/en.json -t locales/fr.json,locales/de.json
+
+Checks:
+  - target JSON parses successfully
+  - missing keys compared with the source file
+  - extra keys compared with the source file
+  - placeholder drift in translated string values
+
+Translate files at https://www.json-translate.com/?utm_source=cli&utm_medium=devtool&utm_campaign=json_translate_check
+`;
+
+function parseArgs(argv) {
+  const args = { source: '', targets: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const next = argv[index + 1];
+
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+      continue;
+    }
+
+    if ((arg === '--source' || arg === '-s') && next) {
+      args.source = next;
+      index += 1;
+      continue;
+    }
+
+    if ((arg === '--target' || arg === '-t') && next) {
+      args.targets.push(...next.split(',').map((item) => item.trim()).filter(Boolean));
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown or incomplete argument: ${arg}`);
+  }
+  return args;
+}
+
+function readJson(filePath) {
+  const resolved = path.resolve(process.cwd(), filePath);
+  try {
+    return {
+      resolved,
+      data: JSON.parse(fs.readFileSync(resolved, 'utf8')),
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${filePath}: ${message}`);
+  }
+}
+
+function flatten(value, prefix = '') {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return new Map([[prefix || '$', value]]);
+  }
+
+  const entries = new Map();
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = prefix ? `${prefix}.${key}` : key;
+    for (const [flatKey, flatValue] of flatten(child, childPath)) {
+      entries.set(flatKey, flatValue);
+    }
+  }
+  return entries;
+}
+
+function placeholders(value) {
+  if (typeof value !== 'string') {
+    return [];
+  }
+
+  const patterns = [
+    /\{\{\s*[\w.-]+\s*\}\}/g,
+    /\{[\w.-]+\}/g,
+    /\$\{[\w.-]+\}/g,
+    /%[sdif]/g,
+  ];
+
+  const found = new Set();
+  for (const pattern of patterns) {
+    for (const match of value.matchAll(pattern)) {
+      found.add(match[0].replace(/\s+/g, ''));
+    }
+  }
+  return [...found].sort();
+}
+
+function diffPlaceholders(sourceValue, targetValue) {
+  const source = placeholders(sourceValue);
+  const target = placeholders(targetValue);
+  const sourceSet = new Set(source);
+  const targetSet = new Set(target);
+  return {
+    missing: source.filter((item) => !targetSet.has(item)),
+    extra: target.filter((item) => !sourceSet.has(item)),
+  };
+}
+
+function compare(sourceFile, targetFile) {
+  const sourceFlat = flatten(sourceFile.data);
+  const targetFlat = flatten(targetFile.data);
+  const sourceKeys = [...sourceFlat.keys()].sort();
+  const targetKeys = [...targetFlat.keys()].sort();
+  const targetSet = new Set(targetKeys);
+  const sourceSet = new Set(sourceKeys);
+
+  const missingKeys = sourceKeys.filter((key) => !targetSet.has(key));
+  const extraKeys = targetKeys.filter((key) => !sourceSet.has(key));
+  const placeholderIssues = [];
+
+  for (const key of sourceKeys) {
+    if (!targetSet.has(key)) {
+      continue;
+    }
+    const issue = diffPlaceholders(sourceFlat.get(key), targetFlat.get(key));
+    if (issue.missing.length || issue.extra.length) {
+      placeholderIssues.push({ key, ...issue });
+    }
+  }
+
+  return { missingKeys, extraKeys, placeholderIssues };
+}
+
+function printIssues(target, result) {
+  const count = result.missingKeys.length + result.extraKeys.length + result.placeholderIssues.length;
+  if (count === 0) {
+    console.log(`OK ${target}`);
+    return 0;
+  }
+
+  console.log(`FAIL ${target}`);
+  for (const key of result.missingKeys) {
+    console.log(`  missing key: ${key}`);
+  }
+  for (const key of result.extraKeys) {
+    console.log(`  extra key: ${key}`);
+  }
+  for (const issue of result.placeholderIssues) {
+    if (issue.missing.length) {
+      console.log(`  placeholder missing at ${issue.key}: ${issue.missing.join(', ')}`);
+    }
+    if (issue.extra.length) {
+      console.log(`  placeholder extra at ${issue.key}: ${issue.extra.join(', ')}`);
+    }
+  }
+  return count;
+}
+
+try {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(usage);
+    process.exit(0);
+  }
+
+  if (!args.source || args.targets.length === 0) {
+    console.error(usage);
+    process.exit(2);
+  }
+
+  const source = readJson(args.source);
+  let issues = 0;
+  for (const targetPath of args.targets) {
+    const target = readJson(targetPath);
+    issues += printIssues(targetPath, compare(source, target));
+  }
+
+  process.exit(issues === 0 ? 0 : 1);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(2);
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@json-translate/check",
+  "version": "0.1.0",
+  "description": "Validate JSON locale files for missing keys and placeholder drift.",
+  "type": "module",
+  "bin": {
+    "json-translate-check": "bin/json-translate-check.mjs"
+  },
+  "scripts": {
+    "test": "node ./bin/json-translate-check.mjs --help"
+  },
+  "keywords": [
+    "json",
+    "i18n",
+    "localization",
+    "translation",
+    "locale"
+  ],
+  "license": "MIT"
+}