champollion 0.3.4 → 0.4.0

package/lib/integrity.js

@@ -14,67 +14,32 @@
  *    or values that are clearly just the source value copy-pasted (same
  *    string in a different locale file = untranslated).
  *
+ * 4. ICU STRUCTURE DAMAGE: a translated variable name, plural/select
+ *    keyword or selector ("{cóúnt, plúrál, óné {…} óthér {…}}"), a lost #
+ *    or printf conversion — the SAME check the sync quality gate applies
+ *    (lib/icu-structure.js), so damage written before the gate existed is
+ *    reported instead of waiting for the app to crash.
+ *
  * Zero external dependencies. All string-based analysis.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { parseARB, flutterLocale } from './format.js';
 import { isICUString, parseICU, getRequiredPluralCategories } from './icu.js';
-import { checkContentPreservation } from './validate.js';
+import { checkContentPreservation, checkICUStructure } from './validate.js';
+import { checkMarkup, pluralGaps, describePluralGap } from './icu-structure.js';
+import { getLanguageCard } from './registers.js';
+import { extractPlaceholders, comparePlaceholders, placeholderSyntax, showPlaceholder } from './placeholders.js';
 
 // -----------------------------------------------------------------
 // Placeholder extraction
 // -----------------------------------------------------------------
 
-/**
- * Extract ICU-style placeholders from a string.
- *
- * Handles:
- *   - Simple: {name}, {count}
- *   - Nested ICU: {count, plural, one {# item} other {# items}}
- *   - React-intl: <bold>text</bold>
- *
- * @param {string} text - Translation string
- * @returns {string[]} Sorted array of placeholder tokens
- */
-function extractPlaceholders(text) {
-  if (typeof text !== 'string') return [];
-
-  const placeholders = new Set();
-
-  // Simple ICU placeholders: {name}, {count}
-  // Match top-level braces only (not nested plurals)
-  const simplePattern = /\{(\w+)(?:[,}])/g;
-  let match;
-  while ((match = simplePattern.exec(text)) !== null) {
-    placeholders.add(match[1]);
-  }
-
-  // React-intl XML tags: <bold>, </bold>, <link>, </link>
-  const xmlPattern = /<\/?(\w+)>/g;
-  while ((match = xmlPattern.exec(text)) !== null) {
-    placeholders.add(`<${match[1]}>`);
-  }
-
-  return [...placeholders].sort();
-}
-
-/**
- * Compare placeholders between source and target strings.
- *
- * @param {string} sourceValue - Source locale value
- * @param {string} targetValue - Target locale value
- * @returns {{ missing: string[], extra: string[] }} Placeholder differences
- */
-function comparePlaceholders(sourceValue, targetValue) {
-  const sourcePH = extractPlaceholders(sourceValue);
-  const targetPH = extractPlaceholders(targetValue);
-
-  const missing = sourcePH.filter(p => !targetPH.includes(p));
-  const extra = targetPH.filter(p => !sourcePH.includes(p));
-
-  return { missing, extra };
-}
+// extractPlaceholders, comparePlaceholders, placeholderSyntax and
+// showPlaceholder live in lib/placeholders.js — one extraction shared with
+// the sync quality gate (lib/validate.js), so sync refuses what verify flags
+// (Round 12). Re-exported below for every existing caller.
 
 // -----------------------------------------------------------------
 // Encoding checks
@@ -316,6 +281,101 @@ function findHollowedValues(sourceFlat, targetFlat, noTranslate = null) {
   return findings;
 }
 
+/**
+ * Find values ON DISK whose ICU MessageFormat / placeholder structure was
+ * damaged — the sync gate's own check (validate.js check 2b), applied to
+ * what is already written. Values identical to their source and no-translate
+ * keys are other checks' business.
+ *
+ * @param {object} sourceFlat - Flattened source locale
+ * @param {object} targetFlat - Flattened target locale
+ * @param {string} targetLang - Target locale (decides which plural categories it may add)
+ * @param {import('./no-translate.js').NoTranslateMatcher} [noTranslate]
+ * @returns {Array<{ key: string, actual: string, reason: string, issues: string[], syntaxes: Array<'icu'|'printf'> }>}
+ */
+function findICUStructureIssues(sourceFlat, targetFlat, targetLang, noTranslate = null) {
+  const findings = [];
+  for (const [key, sourceVal] of Object.entries(sourceFlat)) {
+    const targetVal = targetFlat[key];
+    if (typeof sourceVal !== 'string' || typeof targetVal !== 'string') continue;
+    if (sourceVal === targetVal) continue;
+    if (noTranslate && noTranslate.matches(key, sourceVal)) continue;
+    const damage = checkICUStructure(sourceVal, targetVal, targetLang);
+    // `syntaxes` (parallel to `issues`): 'icu' or 'printf' — which syntax
+    // each finding is about, so a report names a lost %(name)s as printf.
+    if (damage) findings.push({ key, actual: targetVal, reason: damage.reason, issues: damage.issues, syntaxes: damage.syntaxes });
+  }
+  return findings;
+}
+
+/**
+ * Find values ON DISK whose markup no longer matches the source: a tag
+ * opened, closed or nested differently (lib/icu-structure.js checkMarkup —
+ * the gate's own check). Echoes and no-translate keys are other checks'.
+ *
+ * @returns {Array<{ key: string, actual: string, reason: string, issues: string[] }>}
+ */
+function findMarkupIssues(sourceFlat, targetFlat, noTranslate = null) {
+  const findings = [];
+  for (const [key, sourceVal] of Object.entries(sourceFlat)) {
+    const targetVal = targetFlat[key];
+    if (typeof sourceVal !== 'string' || typeof targetVal !== 'string') continue;
+    if (sourceVal === targetVal) continue;
+    if (noTranslate && noTranslate.matches(key, sourceVal)) continue;
+    const damage = checkMarkup(sourceVal, targetVal);
+    if (damage) findings.push({ key, actual: targetVal, reason: damage.reason, issues: damage.issues });
+  }
+  return findings;
+}
+
+/**
+ * Damage in an ARB file OUTSIDE its messages — the parts no flat-map check
+ * sees, and the parts an older JSON sync translated:
+ *   - `@@locale` must name the file's own locale (Flutter's underscore form);
+ *     gen-l10n refuses a file whose @@locale disagrees with its file name;
+ *   - a message's `placeholders` metadata (names and Dart types) is code and
+ *     must equal the source's.
+ * Descriptions are not compared — a translated description is legitimate.
+ * Any sync that writes the file repairs both (it rebuilds the document from
+ * the source), so the finding names a TM-served rebuild.
+ *
+ * @param {string} sourcePath
+ * @param {string} targetPath
+ * @param {string} code - The target file's locale
+ * @returns {Array<{ key: string, reason: string }>}
+ */
+function auditARBDocument(sourcePath, targetPath, code) {
+  const read = (p) => {
+    if (!p || !fs.existsSync(p)) return null;
+    const raw = fs.readFileSync(p, 'utf-8');
+    return raw.trim() ? parseARB(raw, p) : null;
+  };
+  const source = read(sourcePath);
+  const target = read(targetPath);
+  if (!target) return [];
+  const findings = [];
+  const expected = flutterLocale(code);
+  if (Object.prototype.hasOwnProperty.call(target, '@@locale') && target['@@locale'] !== expected) {
+    findings.push({
+      key: '@@locale',
+      reason: `@@locale is ${JSON.stringify(target['@@locale'])} — expected "${expected}" (flutter gen-l10n refuses a file whose @@locale disagrees with its name)`,
+    });
+  }
+  for (const [key, meta] of Object.entries(target)) {
+    if (!key.startsWith('@') || key.startsWith('@@')) continue;
+    const ref = source ? source[key] : undefined;
+    if (!ref || typeof ref !== 'object' || !meta || typeof meta !== 'object') continue;
+    if (ref.placeholders === undefined && meta.placeholders === undefined) continue;
+    if (JSON.stringify(ref.placeholders ?? null) !== JSON.stringify(meta.placeholders ?? null)) {
+      findings.push({
+        key,
+        reason: `placeholder metadata of "${key.slice(1)}" differs from the source (placeholder names and types are code, not text)`,
+      });
+    }
+  }
+  return findings;
+}
+
 /**
  * Find Private Use Area codepoints where script conversion is switched OFF.
  *
@@ -369,17 +429,17 @@ function findOrphanedKeys(sourceFlat, targetFlat) {
 // -----------------------------------------------------------------
 
 /**
- * Check whether ICU plural strings have the correct categories for the target locale.
+ * Check whether ICU plural strings have the plural forms the target locale uses.
  *
- * WHY: Arabic requires {zero, one, two, few, many, other} but if the LLM only
+ * WHY: Arabic uses {zero, one, two, few, many, other} but if the LLM only
  * produces {one, other}, the runtime silently falls back to 'other' for all
  * other quantities — producing wrong text for 0, 2, 3-10, 11-99, etc.
  *
- * This function:
- *   1. Scans source values for ICU plural patterns
- *   2. Parses the corresponding target values
- *   3. Compares their plural categories against what CLDR requires
- *   4. Reports missing categories as warnings
+ * Missing forms follow the SAME everyday/rare rule sync uses
+ * (icu-structure.js pluralGaps): a form ordinary counts reach (Russian
+ * few/many) is an issue; one reached only above 1000 or by fractions (French
+ * `many`) is a note, not a warning — sync already says that is fine, and
+ * integrity warning about it contradicted it (Round 5, Next.js persona).
  *
  * Only triggers on keys where the SOURCE value is an ICU plural string.
  * If the source doesn't use ICU plurals, we don't check (the target shouldn't
@@ -388,10 +448,14 @@ function findOrphanedKeys(sourceFlat, targetFlat) {
  * @param {object} sourceFlat - Flattened source locale
  * @param {object} targetFlat - Flattened target locale
  * @param {string} targetLang - Target locale code
- * @returns {Array<{ key: string, missing: string[], extra: string[] }>}
+ * @returns {{ issues: Array<{ key: string, missing: string[], extra: string[], type: string }>,
+ *   notes: Array<{ key: string, rare: string[], type: string }> }}
+ *   issues: everyday forms missing or categories the locale does not have;
+ *   notes: only forms for large numbers / fractions missing
  */
-function checkPluralCategories(sourceFlat, targetFlat, targetLang) {
+function checkPluralForms(sourceFlat, targetFlat, targetLang, pluralSlots = null) {
   const issues = [];
+  const notes = [];
   const requiredCategories = getRequiredPluralCategories(targetLang);
 
   for (const [key, sourceVal] of Object.entries(sourceFlat)) {
@@ -413,12 +477,11 @@ function checkPluralCategories(sourceFlat, targetFlat, targetLang) {
     if (!targetPluralNode || !targetPluralNode.options) continue;
 
     const targetCategories = Object.keys(targetPluralNode.options);
-
-    // Find missing required categories (ignoring exact-match like =0, =1)
-    const missing = requiredCategories.filter(cat =>
-      !targetCategories.includes(cat) &&
-      !cat.startsWith('=')
-    );
+    // A gettext catalog: only the forms its header has slots for (lib/po.js).
+    const gaps = pluralGaps(sourceVal, targetVal, targetLang, pluralSlots);
+    const missing = [...new Set(gaps.flatMap(g => g.everyday))];
+    const rare = [...new Set(gaps.flatMap(g => g.rare))];
+    const type = gaps[0]?.type || 'cardinal';
 
     // Find unexpected categories (not in CLDR for this locale)
     // Exclude exact-match categories (=0, =1) which are always valid
@@ -428,11 +491,26 @@ function checkPluralCategories(sourceFlat, targetFlat, targetLang) {
     );
 
     if (missing.length > 0 || extra.length > 0) {
-      issues.push({ key, missing, extra });
+      issues.push({ key, missing, extra, type });
+    } else if (rare.length > 0) {
+      notes.push({ key, rare, type });
     }
   }
 
-  return issues;
+  return { issues, notes };
+}
+
+/**
+ * Plural issues only (everyday forms missing, unexpected categories) — the
+ * shape older callers read. See checkPluralForms for the notes.
+ *
+ * @param {object} sourceFlat
+ * @param {object} targetFlat
+ * @param {string} targetLang
+ * @returns {Array<{ key: string, missing: string[], extra: string[] }>}
+ */
+function checkPluralCategories(sourceFlat, targetFlat, targetLang) {
+  return checkPluralForms(sourceFlat, targetFlat, targetLang).issues;
 }
 
 // -----------------------------------------------------------------
@@ -485,8 +563,17 @@ function auditLocalePair(sourceFlat, targetFlat, targetLang, options = {}) {
   const noTranslateDrift = findNoTranslateDrift(sourceFlat, targetFlat, noTranslate);
   const unexpectedPua = findUnexpectedPua(targetFlat, options.scriptExpectation || null);
   const hollowedValues = findHollowedValues(sourceFlat, targetFlat, noTranslate);
+  const icuIssues = findICUStructureIssues(sourceFlat, targetFlat, targetLang, noTranslate);
+  const markupIssues = findMarkupIssues(sourceFlat, targetFlat, noTranslate);
+  // A tag-only placeholder difference is the markup check's finding, said
+  // precisely there (which tag, opened or closed) — not twice.
+  const markupKeys = new Set(markupIssues.map(m => m.key));
+  for (let i = placeholderIssues.length - 1; i >= 0; i--) {
+    const p = placeholderIssues[i];
+    if (markupKeys.has(p.key) && [...p.missing, ...p.extra].every(t => t.startsWith('<'))) placeholderIssues.splice(i, 1);
+  }
   const orphans = findOrphanedKeys(sourceFlat, targetFlat);
-  const pluralIssues = checkPluralCategories(sourceFlat, targetFlat, targetLang);
+  const { issues: pluralIssues, notes: pluralNotes } = checkPluralForms(sourceFlat, targetFlat, targetLang, options.pluralSlots || null);
 
   // File-level BOM check. When the caller passes file paths, REPORT a UTF-8
   // BOM as an issue rather than letting it silently corrupt the first key /
@@ -498,7 +585,7 @@ function auditLocalePair(sourceFlat, targetFlat, targetLang, options = {}) {
     } catch { /* unreadable file — not an integrity finding */ }
   }
 
-  return { placeholderIssues, encodingIssues, copies, orphans, noTranslateDrift, unexpectedPua, hollowedValues, pluralIssues, bomFiles };
+  return { placeholderIssues, encodingIssues, copies, orphans, noTranslateDrift, unexpectedPua, hollowedValues, icuIssues, markupIssues, pluralIssues, pluralNotes, bomFiles };
 }
 
 /**
@@ -519,6 +606,26 @@ function visualize(value) {
   return JSON.stringify(escaped);
 }
 
+/**
+ * Plural forms only large numbers or fractions reach (French `many`): said,
+ * never warned — the rule sync uses (icu-structure.js pluralGaps).
+ *
+ * @param {string} targetLang
+ * @param {object} audit
+ * @returns {string[]}
+ */
+function pluralNoteLines(targetLang, audit) {
+  const notes = audit.pluralNotes || [];
+  if (notes.length === 0) return [];
+  const langName = getLanguageCard(targetLang)?.name || targetLang;
+  const lines = [`\n  [INFO] PLURAL FORMS FOR LARGE NUMBERS ONLY (${notes.length}) — not a problem`];
+  for (const note of notes.slice(0, 10)) {
+    lines.push(`  ├── ${note.key}: ${describePluralGap(targetLang, note.rare, note.type || 'cardinal', langName, 'rare')}`);
+  }
+  if (notes.length > 10) lines.push(`  └── ... and ${notes.length - 10} more`);
+  return lines;
+}
+
 /**
  * Format an integrity audit result as a console report.
  *
@@ -534,17 +641,22 @@ function formatIntegrityReport(targetLang, audit) {
   const drift = audit.noTranslateDrift || [];
   const unexpectedPua = audit.unexpectedPua || [];
   const hollowedValues = audit.hollowedValues || [];
+  const icuIssues = audit.icuIssues || [];
+  const documentIssues = audit.documentIssues || [];
   const totalIssues = placeholderIssues.length + encodingIssues.length +
     copies.length + orphans.length + (audit.pluralIssues?.length || 0) +
-    bomFiles.length + drift.length + unexpectedPua.length + hollowedValues.length;
+    bomFiles.length + drift.length + unexpectedPua.length + hollowedValues.length + icuIssues.length
+    + documentIssues.length;
 
   lines.push(`\n  Integrity Audit: ${targetLang}`);
   lines.push(`  ${'─'.repeat(40)}`);
 
   if (totalIssues === 0) {
-    lines.push('  [OK] All checks passed — no issues found');
+    // Structure, not meaning — say which (Round 3, hospital persona).
+    lines.push('  [OK] Structural checks passed — no issues found (the meaning is not checked)');
+    lines.push(...pluralNoteLines(targetLang, audit));
     lines.push('');
-    return lines.join('\n');
+    return lines.join('\n').replace(/\u0004/g, '\u2404');
   }
 
   // Placeholder issues
@@ -564,6 +676,32 @@ function formatIntegrityReport(targetLang, audit) {
     }
   }
 
+  // ICU structure damage — translated keywords/variables, lost # or %d
+  if (icuIssues.length > 0) {
+    lines.push(`\n  ICU STRUCTURE DAMAGE (${icuIssues.length})`);
+    lines.push('  └── Syntax that was translated or lost — the app cannot format these.');
+    lines.push('      Re-translate: `champollion sync --force-keys <key>` (the cached copy is evicted):');
+    for (const issue of icuIssues.slice(0, 10)) {
+      lines.push(`      ${issue.key}: ${issue.issues.join('; ')}`);
+      lines.push(`        actual: ${visualize(issue.actual)}`);
+    }
+    if (icuIssues.length > 10) {
+      lines.push(`      ... and ${icuIssues.length - 10} more`);
+    }
+  }
+
+  // Document damage (ARB @@locale / placeholder metadata)
+  if (documentIssues.length > 0) {
+    lines.push(`\n  FILE STRUCTURE DAMAGE (${documentIssues.length})`);
+    lines.push(`  └── Outside the messages. Any sync that rewrites the file repairs it — e.g. \`champollion sync --pair <src>:${targetLang} --force\` (served from the cache):`);
+    for (const issue of documentIssues.slice(0, 10)) {
+      lines.push(`      ${issue.key}: ${issue.reason}`);
+    }
+    if (documentIssues.length > 10) {
+      lines.push(`      ... and ${documentIssues.length - 10} more`);
+    }
+  }
+
   // Encoding issues
   if (encodingIssues.length > 0) {
     lines.push(`\n  [WARN] ENCODING ISSUES (${encodingIssues.length})`);
@@ -649,13 +787,16 @@ function formatIntegrityReport(targetLang, audit) {
     }
   }
 
-  // Plural category issues
+  // Plural category issues — the same everyday/rare rule and wording as sync
+  // (icu-structure.js pluralGaps / describePluralGap).
+  const langName = getLanguageCard(targetLang)?.name || targetLang;
   if (audit.pluralIssues && audit.pluralIssues.length > 0) {
     lines.push(`\n  [WARN] PLURAL CATEGORY ISSUES (${audit.pluralIssues.length})`);
     for (const issue of audit.pluralIssues.slice(0, 10)) {
       lines.push(`  ├── ${issue.key}`);
       if (issue.missing.length > 0) {
-        lines.push(`  │   Missing categories: ${issue.missing.join(', ')}`);
+        lines.push(`  │   Missing: ${describePluralGap(targetLang, issue.missing, issue.type || 'cardinal', langName, 'everyday')}`
+          + ' — the app shows the "other" form for those counts');
       }
       if (issue.extra.length > 0) {
         lines.push(`  │   Unexpected categories: ${issue.extra.join(', ')}`);
@@ -665,13 +806,17 @@ function formatIntegrityReport(targetLang, audit) {
       lines.push(`  └── ... and ${audit.pluralIssues.length - 10} more`);
     }
   }
+  lines.push(...pluralNoteLines(targetLang, audit));
 
   lines.push('');
-  return lines.join('\n');
+  // gettext context keys (msgctxt\u0004msgid): print U+0004 visibly as "␄".
+  return lines.join('\n').replace(/\u0004/g, '\u2404');
 }
 
 export {
   extractPlaceholders,
+  placeholderSyntax,
+  showPlaceholder,
   comparePlaceholders,
   checkEncoding,
   hasBOM,
@@ -679,9 +824,12 @@ export {
   findNoTranslateDrift,
   findUnexpectedPua,
   findHollowedValues,
+  findICUStructureIssues,
+  auditARBDocument,
   isLocaleInvariant,
   findOrphanedKeys,
   checkPluralCategories,
+  checkPluralForms,
   auditLocalePair,
   formatIntegrityReport,
   visualize,

package/lib/language-pair.js

@@ -0,0 +1,157 @@
+/**
+ * How the network commands read and write a language pair — one parser for
+ * `register-corpus --pair`, `leaderboard --pair`, `recommend <pair>` and the
+ * pair fields of `submit`, so they accept the same spellings and print the
+ * same one.
+ *
+ * WRITTEN (what these commands print): source>target — `eng>crk`. It is the
+ * form the leaderboard stores (mt-eval's publish writes `eng>crk`), the form
+ * the harness's own --pair flags take, and the form the docs show. In a
+ * command it is quoted, `--pair "eng>crk"`: an unquoted > makes the shell
+ * write the output to a file.
+ *
+ * READ (what they accept):
+ *   eng>crk  eng-crk  eng:crk  eng→crk  eng->crk  eng,crk  "eng crk"
+ *
+ * The rule that keeps this unambiguous: `-` is also the separator INSIDE a
+ * locale code (pt-BR, sr-Latn, crk-Cans). So
+ *   - with an explicit separator (> : → -> , or a space), the value splits
+ *     there and either side may carry its own hyphens: "en>pt-BR";
+ *   - with hyphens only, the value is a pair only when it is exactly two bare
+ *     language codes of two or three letters: eng-crk, en-fr. crk-Cans is one
+ *     code with a script subtag, not crk → Cans; en-pt-BR could be en + pt-BR
+ *     or en-PT + BR (and `br` is Breton). Those are refused, never guessed,
+ *     and the refusal names the readings in the written form.
+ * This is the harness's own rule (arena/mt_eval_harness/pair_notation.py),
+ * so `mt-eval` and `champollion` read a dash pair the same way.
+ *
+ * Project pairs are a different key space: `sync`, `verify` and `serve`
+ * --pair name pairs of champollion.config.json, whose keys are written
+ * `en:fr`. They go through lib/pairs.js (filterPairGraph), which reads the
+ * same separators and settles a many-hyphen dash form against the pairs the
+ * project configures.
+ *
+ * @module language-pair
+ */
+
+/** The separator a written pair uses. */
+export const PAIR_SEPARATOR = '>';
+
+/** One line for help text: how to write a pair, and what else is accepted. */
+export const PAIR_NOTATION_HELP =
+  'source>target, e.g. "eng>crk" (quote it: an unquoted > sends the output to a file). '
+  + 'eng-crk, eng:crk and "eng crk" are read the same way; a code with its own hyphen (pt-BR) needs >, e.g. "eng>pt-BR"';
+
+// Longest first, so "->" is never read as "-" followed by ">".
+const EXPLICIT_SEPARATORS = ['->', '→', '>', ':', ','];
+
+// A language code or locale tag: letters first, then letters/digits, with
+// optional -/_ subtags (eng, crk, pt-BR, sr-Latn, zh-Hant-TW, ace_Arab, qaa).
+const CODE_SHAPE = /^[A-Za-z][A-Za-z0-9]*(?:[-_][A-Za-z0-9]+)*$/;
+
+// The dash form: exactly two bare ISO 639 codes (the harness's _HYPHEN_PAIR).
+const DASH_PAIR = /^([A-Za-z]{2,3})-([A-Za-z]{2,3})$/;
+
+/**
+ * Write a pair in the one form these commands print: `eng>crk`.
+ *
+ * @param {{source: string, target: string}} pair
+ * @returns {string}
+ */
+export function formatLanguagePair(pair) {
+  return `${pair.source}${PAIR_SEPARATOR}${pair.target}`;
+}
+
+/**
+ * The same, ready to paste into a command: `"eng>crk"` (quoted for the > ).
+ *
+ * @param {{source: string, target: string}} pair
+ * @returns {string}
+ */
+export function quotedLanguagePair(pair) {
+  return `"${formatLanguagePair(pair)}"`;
+}
+
+function sides(source, target, shown) {
+  const s = source.trim();
+  const t = target.trim();
+  if (!s) return { ok: false, error: `${shown} names no source language — write source>target, e.g. "eng>crk".` };
+  if (!t) return { ok: false, error: `${shown} names no target language — write source>target, e.g. "eng>crk".` };
+  for (const code of [s, t]) {
+    if (!CODE_SHAPE.test(code)) {
+      return {
+        ok: false,
+        error: `${shown}: "${code}" is not a language code (letters and digits, with -subtags such as pt-BR). `
+          + 'Write the pair source>target, e.g. "eng>crk".',
+      };
+    }
+  }
+  return { ok: true, source: s, target: t };
+}
+
+/**
+ * Read a language pair in any accepted spelling (see the module comment).
+ * Codes keep the case they were typed in — callers that key on lower case
+ * (card ids, the leaderboard) lower it themselves.
+ *
+ * @param {*} value the raw value (a flag, a positional, a form line)
+ * @param {object} [o]
+ * @param {string} [o.label] how to name the value in an error (default: the value quoted)
+ * @returns {{ok: true, source: string, target: string} | {ok: false, error: string}}
+ */
+export function parseLanguagePair(value, { label } = {}) {
+  if (value === undefined || value === null || value === true || value === false) {
+    return { ok: false, error: `${label || 'The pair'} needs a value: source>target, e.g. "eng>crk" (or eng-crk).` };
+  }
+  const raw = String(value).trim();
+  const shown = label ? `${label} ${raw}` : `"${raw}"`;
+  if (!raw) return { ok: false, error: `${label || 'The pair'} is empty — write source>target, e.g. "eng>crk" (or eng-crk).` };
+
+  for (const sep of EXPLICIT_SEPARATORS) {
+    if (!raw.includes(sep)) continue;
+    const parts = raw.split(sep);
+    if (parts.length !== 2) {
+      return { ok: false, error: `${shown} has more than one "${sep}" — a pair is two codes: source>target, e.g. "eng>crk".` };
+    }
+    return sides(parts[0], parts[1], shown);
+  }
+
+  if (/\s/.test(raw)) {
+    const words = raw.split(/\s+/);
+    if (words.length === 2) return sides(words[0], words[1], shown);
+    if (words.length === 3 && words[1] === '-') return sides(words[0], words[2], shown);
+    return { ok: false, error: `${shown} is more than two codes — a pair is source>target, e.g. "eng>crk".` };
+  }
+
+  const dash = DASH_PAIR.exec(raw);
+  if (dash) return { ok: true, source: dash[1], target: dash[2] };
+  const hyphens = [];
+  for (let i = raw.indexOf('-'); i !== -1; i = raw.indexOf('-', i + 1)) hyphens.push(i);
+  if (hyphens.length === 1) {
+    // One hyphen, but a side is not a bare 2–3 letter code: crk-Cans is a
+    // code with a script subtag, not a pair.
+    return {
+      ok: false,
+      error: `${shown} is not read as a pair: with a hyphen, a pair is two language codes of two or three `
+        + 'letters (eng-crk), and a side of this one is not (crk-Cans, say, is one code with a script subtag). '
+        + 'Write the pair with > between the two codes, e.g. "eng>crk-Cans".',
+    };
+  }
+  if (hyphens.length === 0) {
+    // One code, no separator. The commonest way to get here: `--pair eng>crk`
+    // typed without quotes — the shell takes `>crk` as "write the output to a
+    // file named crk" and passes just `eng`.
+    return {
+      ok: false,
+      error: `${shown} names one language; a pair names two, source first: "eng>crk" or eng-crk. `
+        + `If you typed ${raw}>… without quotes, the shell read the > as "send the output to a file" `
+        + '(and may have made a file named after the second code): quote the pair, or use the dash form.',
+    };
+  }
+  const readings = hyphens.map((i) => quotedLanguagePair({ source: raw.slice(0, i), target: raw.slice(i + 1) }));
+  return {
+    ok: false,
+    error: `${shown} has ${hyphens.length} hyphens, so it can be read more than one way (${readings.join(' or ')}). `
+      + 'A code with its own hyphen (pt-BR, sr-Latn) needs > between the two codes — write the one you mean.',
+  };
+}