champollion 0.3.3

package/lib/translate-pair.js

@@ -0,0 +1,197 @@
+/**
+ * translate-pair.js — Shared translation pipeline for a single pair
+ *
+ * Encapsulates the common sequence used by both the standard sync path
+ * and the Docusaurus sync path:
+ *
+ *   1. TM partition: split keys into cached hits and API misses
+ *   2. API call: translate the misses via translateBatch
+ *   3. Quality gate: validate translations (hallucination, script, length)
+ *      — TM hits that fail are evicted so the poison cannot be re-served
+ *      — gate failures get ONE feedback retry (the rejection reason is
+ *        injected into the prompt; a blind retry at temperature 0 would
+ *        return byte-identical output)
+ *   4. TM store: cache only gate-validated API translations
+ *
+ * ORDER MATTERS: the TM must only ever hold gate-validated values. An
+ * earlier version stored API output before validation; one degenerate
+ * response (e.g. "for translating" → "吗") then poisoned the cache — every
+ * later sync served it, failed the gate, and never consulted the API again.
+ *
+ * Callers get back a structured result and handle their own control flow
+ * (fallback decisions, error messages, script conversion, etc.) because
+ * those details differ between sync paths.
+ */
+
+import { translateBatch } from './translate.js';
+import { validateTranslations, logGateFailures } from './validate.js';
+import { partitionByTM, storeTM, evictTM, tmMethodKey } from './tm.js';
+import { output } from './output.js';
+
+/**
+ * Translate a set of string keys through the TM + API + quality gate pipeline.
+ *
+ * @param {string[]} stringKeys - Keys to translate (must be string-valued in sourceFlat)
+ * @param {object} sourceFlat - Full flattened source locale map
+ * @param {object} pairConfig - Pair configuration (target, method, model, batchSize, etc.)
+ * @param {string} pairKey - Human-readable pair identifier for logging (e.g. "en→fr")
+ * @param {object} options
+ * @param {string} options.apiKey - API key for translation provider
+ * @param {object} options.tm - Translation Memory object (mutable — entries are stored in-place)
+ * @param {string} options.targetCode - Target language code
+ * @param {object} [options.descriptions] - Optional key descriptions (Docusaurus format)
+ * @param {Function} [options.onProgress] - Progress callback: (completed, total) => void
+ * @returns {Promise<TranslateResult>}
+ *
+ * @typedef {object} TranslateResult
+ * @property {object|null} translated - Validated translations, or null if all failed
+ * @property {number} tmHitCount - Number of keys served from TM cache
+ * @property {Array} failures - Quality gate failures (for caller logging)
+ * @property {boolean} apiCalled - Whether the API was actually invoked
+ * @property {boolean} apiReturnedNull - Whether the API was called but returned null
+ */
+export async function translateAndValidate(stringKeys, sourceFlat, pairConfig, pairKey, options) {
+  const { apiKey, tm, targetCode, descriptions } = options;
+  const method = pairConfig.method || 'llm';
+
+  // TM entries are keyed on the FULL method key (method|model|register|coaching),
+  // not the bare method name: switching model, register, or coaching must be a
+  // cache miss, never a silent re-serve of old-style translations. See tm.js.
+  const tmKey = tmMethodKey(pairConfig);
+
+  // Step 1: TM partition — serve cached hits, identify API misses
+  const { hits: tmHits, misses: tmMisses } = partitionByTM(
+    tm, sourceFlat, stringKeys, targetCode, tmKey
+  );
+
+  const tmHitCount = Object.keys(tmHits).length;
+  if (tmHitCount > 0) {
+    output.info(`[TM] ${tmHitCount} key(s) served from cache`);
+  }
+
+  // Start with TM hits as the base
+  const translated = { ...tmHits };
+  let apiCalled = false;
+  let apiReturnedNull = false;
+
+  // Provenance: keys whose current value came from the API this run.
+  // Only these are eligible for TM storage after validation, and only
+  // non-API (TM-served) failures need cache eviction.
+  const apiKeys = new Set();
+
+  const batchOptions = {
+    apiKey,
+    model: pairConfig.model,
+    batchSize: pairConfig.batchSize,
+    onProgress: options.onProgress || null,
+  };
+
+  // Docusaurus passes descriptions for disambiguation context
+  if (descriptions) {
+    batchOptions.descriptions = descriptions;
+  }
+
+  // Step 2: API call for misses
+  if (tmMisses.length > 0) {
+    output.progress(`     Translating ${tmMisses.length} key(s) to ${pairConfig.name} (${method})...`);
+
+    const apiResult = await translateBatch(tmMisses, sourceFlat, pairConfig, batchOptions);
+    apiCalled = true;
+
+    if (apiResult) {
+      Object.assign(translated, apiResult);
+      for (const k of Object.keys(apiResult)) apiKeys.add(k);
+    } else {
+      apiReturnedNull = true;
+    }
+  }
+
+  // Step 3: Quality gate — validate translations before accepting
+  let validated = {};
+  let failures = [];
+  if (Object.keys(translated).length > 0) {
+    const result = validateTranslations(translated, sourceFlat, pairConfig);
+    validated = result.validated;
+    failures = result.failures;
+  }
+
+  // Step 3a: Evict poisoned TM entries. A TM-served value that fails the
+  // gate would otherwise be re-served (and re-fail) on every future sync
+  // without the API ever being consulted again.
+  for (const f of failures) {
+    if (f.key in tmHits && !apiKeys.has(f.key) && typeof sourceFlat[f.key] === 'string') {
+      evictTM(tm, sourceFlat[f.key], targetCode, tmKey);
+    }
+  }
+
+  // Step 3b: Feedback retry — one corrective round for gate failures.
+  // The rejection reason is injected as per-key context so the prompt
+  // actually changes; without it, a temperature-0 retry is a no-op.
+  //
+  // NOT gated on `apiKey`: that is the OpenRouter key, and the retry runs
+  // through the pair's OWN method — google-translate/deepl/direct providers
+  // carry their own credentials. The old `&& apiKey` guard silently skipped
+  // the corrective round for every direct provider, which meant a TM entry
+  // evicted by the gate (step 3a) was only re-billed on the NEXT sync — a
+  // two-pass heal nobody asked for. A method that genuinely cannot run
+  // returns null here and the failures simply stand.
+  if (failures.length > 0) {
+    const retryKeys = failures
+      .map(f => f.key)
+      .filter(k => typeof sourceFlat[k] === 'string');
+
+    if (retryKeys.length > 0) {
+      output.progress(`     Quality gate rejected ${retryKeys.length} key(s) — retrying with feedback...`);
+
+      const feedbackDescriptions = { ...(descriptions || {}) };
+      for (const f of failures) {
+        const rejected = String(f.value ?? '').slice(0, 60);
+        const base = feedbackDescriptions[f.key] ? `${feedbackDescriptions[f.key]} — ` : '';
+        feedbackDescriptions[f.key] =
+          `${base}RETRY: a previous attempt ("${rejected}") was rejected by the quality gate: ${f.reason}. ` +
+          `Provide a complete, self-contained ${pairConfig.name} translation of this exact string.`;
+      }
+
+      const retryResult = await translateBatch(retryKeys, sourceFlat, pairConfig, {
+        ...batchOptions,
+        onProgress: null, // avoid double-counting progress
+        descriptions: feedbackDescriptions,
+      });
+      apiCalled = true;
+
+      if (retryResult) {
+        const retryValidation = validateTranslations(retryResult, sourceFlat, pairConfig);
+        Object.assign(validated, retryValidation.validated);
+        for (const k of Object.keys(retryValidation.validated)) apiKeys.add(k);
+
+        // Keys that passed on retry are no longer failures; keys the retry
+        // produced a fresh (still failing) value for get the newer record.
+        const passed = new Set(Object.keys(retryValidation.validated));
+        const retryFailureByKey = new Map(retryValidation.failures.map(f => [f.key, f]));
+        failures = failures
+          .filter(f => !passed.has(f.key))
+          .map(f => retryFailureByKey.get(f.key) || f);
+      }
+    }
+  }
+
+  if (failures.length > 0) {
+    logGateFailures(failures, pairKey);
+  }
+
+  // Step 4: TM store — only gate-validated values that came from the API.
+  // TM hits are already cached; unvalidated output must never enter the TM.
+  for (const [k, v] of Object.entries(validated)) {
+    if (apiKeys.has(k) && typeof v === 'string' && typeof sourceFlat[k] === 'string') {
+      storeTM(tm, sourceFlat[k], targetCode, tmKey, v);
+    }
+  }
+
+  return {
+    translated: Object.keys(validated).length > 0 ? validated : null,
+    tmHitCount,
+    failures,
+    apiCalled,
+    apiReturnedNull,
+  };
+}

package/lib/translate.js

@@ -0,0 +1,203 @@
+/**
+ * Translation orchestrator — delegates to method-specific implementations.
+ *
+ * v3 ARCHITECTURE:
+ *   In v2, this module contained all the OpenRouter API logic directly.
+ *   In v3, the actual API calls live in lib/methods/llm.js (and future
+ *   method implementations). This module is now the orchestrator:
+ *
+ *   1. Receives a pair config (from pairs.js) with method/model/qualityTier
+ *   2. Instantiates the correct TranslationMethod subclass
+ *   3. Delegates the translation call
+ *   4. Returns the result
+ *
+ *   This separation means adding a new translation strategy (e.g., fst-gated,
+ *   human-review) requires only implementing a new method class — zero changes
+ *   to the sync pipeline or any other consumer.
+ *
+ * BACKWARD COMPAT:
+ *   The exported API (translateBatch, translateRawContent, isUnsafeKey) is
+ *   preserved so that sync.js and content.js continue to work without
+ *   changes during the transition. The only difference is that translateBatch
+ *   now accepts an optional pairConfig as the third argument.
+ */
+
+import { LLMMethod, buildPrompt, inferKeyTypes } from './methods/llm.js';
+import { isUnsafeKey } from './security.js';
+import { LLMCoachedMethod } from './methods/llm-coached.js';
+import { GoogleTranslateMethod } from './methods/google-translate.js';
+import { APIMethod } from './methods/api.js';
+import { DeepLMethod } from './methods/deepl.js';
+import { MicrosoftTranslatorMethod } from './methods/microsoft-translator.js';
+import { LibreTranslateMethod } from './methods/libretranslate.js';
+import { ApertiumMethod } from './methods/apertium.js';
+import { TildeMethod } from './methods/tilde.js';
+import { TranslatedMethod } from './methods/translated.js';
+import { OpenAIMethod } from './methods/openai.js';
+import { AnthropicMethod } from './methods/anthropic.js';
+import { GeminiMethod } from './methods/gemini.js';
+import { LocalMethod } from './methods/local.js';
+import { ExternalMethod } from './methods/external.js';
+import { DEFAULT_OPENROUTER_MODEL } from './config.js';
+import { manifestEntries, cliNameFor } from './method-manifest.js';
+import { assertRoutable } from './commercial-eligibility.js';
+
+/**
+ * Registry of available translation methods.
+ *
+ * Each entry maps a method name to its constructor.
+ * To add a new method:
+ *   1. Create the class in lib/methods/<name>.js
+ *   2. Register it here
+ *   3. Users can reference it in config pairs: { method: "<name>" }
+ */
+const METHOD_REGISTRY = {
+  'llm': LLMMethod,
+  'llm-coached': LLMCoachedMethod,
+  'google-translate': GoogleTranslateMethod,
+  'api': APIMethod,
+  'deepl': DeepLMethod,
+  'microsoft-translator': MicrosoftTranslatorMethod,
+  'libretranslate': LibreTranslateMethod,
+  'apertium': ApertiumMethod,
+  'tilde': TildeMethod,
+  'translated': TranslatedMethod,
+  'openai': OpenAIMethod,
+  'anthropic': AnthropicMethod,
+  'gemini': GeminiMethod,
+  'local': LocalMethod,
+  'external': ExternalMethod,
+};
+
+/**
+ * Find a shared-registry entry that exists but is NOT served in the CLI runtime.
+ *
+ * An entry is harness-only when it declares `runtimes` and that list excludes
+ * 'cli' (e.g. amazon-translate, local-model). Matches against both the
+ * canonical manifest name and the CLI alias (cli_name). Returns null when the
+ * manifest is absent (standalone package) or the name is genuinely unknown.
+ *
+ * @param {string} methodName
+ * @returns {{ name: string, entry: object } | null}
+ */
+function findHarnessOnlyEntry(methodName) {
+  for (const [name, entry] of Object.entries(manifestEntries())) {
+    if (name !== methodName && cliNameFor(name, entry) !== methodName) continue;
+    if (Array.isArray(entry.runtimes) && !entry.runtimes.includes('cli')) {
+      return { name, entry };
+    }
+    // Found a matching entry that DOES run in the CLI — not the harness-only case.
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Get a TranslationMethod instance for the given method name.
+ *
+ * **This is the routing-time licence gate.** Every translation in the CLI is
+ * dispatched through here, so it is the one place that can refuse a route.
+ * When the caller is operating a COMMERCIAL lane — a paid routing API, a
+ * billed `champollion serve` deployment — a method whose licence does not
+ * permit commercial use is refused before it can be instantiated, rather
+ * than warned about after the fact (lib/provenance.js reports; this
+ * enforces). The default lane is non-commercial and is never gated: NC and
+ * copyleft engines are legitimate there, and that is the open project.
+ *
+ * The lane comes from the pair config (`useContext`), so it travels with the
+ * route rather than being global state.
+ *
+ * @param {string} methodName - Method name from pair config
+ * @param {import('./types.js').PairConfig} [pluginContext] - Plugin context for API methods
+ * @returns {import('./methods/base.js').TranslationMethod} Method instance
+ * @throws {CommercialRouteBlockedError} when the lane is commercial and the
+ *   method is not cleared for it
+ */
+function getMethod(methodName, pluginContext) {
+  // Gate FIRST: an ineligible method must be refused on licence grounds, not
+  // on "unknown method", and must never reach construction.
+  assertRoutable(methodName, {
+    useContext: pluginContext?.useContext,
+    pluginProvenance: pluginContext?.pluginProvenance,
+  });
+
+  const MethodClass = METHOD_REGISTRY[methodName];
+  if (!MethodClass) {
+    // Before declaring it unknown (which reads like a typo), check whether this
+    // is a real, documented engine that simply has no CLI adapter yet. Engines
+    // such as `amazon-translate` and `local-model` are declared harness-only in
+    // the shared method registry (runtimes: ["harness"]). Surfacing them as
+    // "Unknown method" misleads the user into thinking they misspelled it.
+    const harnessOnly = findHarnessOnlyEntry(methodName);
+    if (harnessOnly) {
+      throw new Error(
+        `Translation engine "${methodName}" is harness-only — it has no CLI ` +
+        `adapter yet, so \`champollion\` cannot run it. Run it with the ` +
+        `evaluation harness instead:\n` +
+        `  mt-eval run --method ${methodName}`
+      );
+    }
+    const known = Object.keys(METHOD_REGISTRY).join(', ');
+    throw new Error(
+      `Unknown translation method "${methodName}". ` +
+      `Available methods: ${known}. ` +
+      `Check your champollion.config.json pairs configuration.`
+    );
+  }
+
+  // APIMethod needs plugin context (endpoint, provenance, quality tier)
+  if (methodName === 'api' && pluginContext) {
+    return new MethodClass({
+      endpoint: pluginContext.endpoint,
+      methodName: pluginContext.pluginName,
+      methodVersion: pluginContext.pluginVersion,
+      qualityTier: pluginContext.qualityTier,
+      provenance: pluginContext.pluginProvenance,
+    });
+  }
+
+  // ExternalMethod needs methodPath to find the Python plugin directory
+  if (methodName === 'external') {
+    return new MethodClass({
+      methodPath: pluginContext?.methodPath || null,
+    });
+  }
+
+  return new MethodClass();
+}
+
+/**
+ * Translate a batch of key-value pairs using the method specified in the pair config.
+ *
+ * @param {string[]} keys - Flat dot-notation keys to translate
+ * @param {object} sourceFlat - Full flattened source locale
+ * @param {import('./types.js').PairConfig} pairConfig - Pair config with method, model, register, etc.
+ * @param {object} options - { apiKey, model, batchSize }
+ * @returns {object|null} Map of key → translated value, or null
+ */
+async function translateBatch(keys, sourceFlat, pairConfig, options) {
+  const method = getMethod(pairConfig.method || 'llm', pairConfig);
+  return method.translate(keys, sourceFlat, pairConfig, options);
+}
+
+/**
+ * Translate freeform text content (e.g., Markdown body).
+ *
+ * @param {string} prompt - Complete translation prompt
+ * @param {object} options - { apiKey, model } or { apiKey, pairConfig }
+ * @returns {string|null} Translated text, or null on failure
+ */
+async function translateRawContent(prompt, options) {
+  const pairConfig = options.pairConfig || {
+    model: options.model || DEFAULT_OPENROUTER_MODEL,
+    method: 'llm',
+  };
+
+  // Pass the pair config as plugin context so methods that need it
+  // (api → endpoint, external → methodPath) are constructed the same
+  // way here as on the key-value path in translateBatch.
+  const method = getMethod(pairConfig.method, pairConfig);
+  return method.translateContent(prompt, pairConfig, options);
+}
+
+export { translateBatch, translateRawContent, buildPrompt, isUnsafeKey, inferKeyTypes, getMethod, METHOD_REGISTRY };

package/lib/types.js

@@ -0,0 +1,230 @@
+/**
+ * Shared type definitions for champollion.
+ *
+ * This file contains JSDoc @typedef declarations for the core data shapes
+ * that flow between modules. It has no runtime code — it exists only so
+ * that editors can resolve type references via imports.
+ *
+ * USAGE IN OTHER MODULES:
+ *   /** @typedef {import('./types.js').PairConfig} PairConfig * /
+ *
+ *   Or, for VS Code auto-resolution without explicit import, just reference
+ *   the type name — jsconfig.json's include paths make these globally visible.
+ */
+
+// -----------------------------------------------------------------
+// ChampollionConfig — the fully resolved project configuration
+// Produced by: config.js:resolveConfig()
+// Consumed by: sync.js, commands/*, seo.js, lint.js, pairs.js
+// -----------------------------------------------------------------
+
+/**
+ * @typedef {object} ChampollionConfig
+ * @property {number} version - Config schema version (currently 3)
+ * @property {string} inputLocale - Source locale code (e.g., 'en')
+ * @property {string} baseUrl - Site base URL for SEO commands
+ * @property {string} localesDir - Absolute path to locale files directory
+ * @property {string|null} contentDir - Hugo/Docusaurus content directory, or null if disabled
+ * @property {string[]|null} translatableFields - Override for content translatable fields, or null for defaults
+ * @property {Array<string>|object} languages - Target languages (array of codes or object with config)
+ * @property {Object<string, LanguageConfig>} [resolvedLanguages] - Fully resolved language map (code → config). Set by resolveConfig.
+ * @property {string[]} noTranslate - Dot-path keys / glob patterns whose value is copied verbatim to every locale (e.g. ['**.url']). Never sent to a backend, gated, or billed.
+ * @property {boolean} noTranslateUrls - Auto-treat source values that are bare `scheme://` URLs as no-translate (default true)
+ * @property {object|null} pairs - Advanced per-pair overrides, or null
+ * @property {string} model - Default translation model (e.g., 'openai/gpt-4o-mini')
+ * @property {string} defaultMethod - Global default method: 'llm', 'google-translate', 'api'
+ * @property {number} batchSize - Default batch size for translation calls
+ * @property {string} fallbackPrefix - Prefix for untranslated fallback values (default: '[EN] ')
+ * @property {string} apiKeyEnvVar - Environment variable name for the API key
+ * @property {string} format - Locale file format: 'json', 'toml', 'yaml', 'auto', 'docusaurus'
+ * @property {string[]} [forceKeys] - Dot-notation keys to force re-translate (from --force-keys). Set by resolveConfig.
+ * @property {{ srcDir: string|null, ignore: string[], minLength: number }} lint - Lint config
+ * @property {{ urlPattern: string, pages: string[]|null }} seo - SEO config
+ * @property {{ output: string|null, autoGenerate: boolean }} typegen - Type generation config
+ */
+
+// -----------------------------------------------------------------
+// PairConfig — a single source→target translation pair
+// Produced by: pairs.js:resolvePairs(), enriched by plugins.js
+// Consumed by: translate.js, methods/*.js, sync.js, provenance.js
+// -----------------------------------------------------------------
+
+/**
+ * @typedef {object} PairConfig
+ * @property {string} source - Source locale code (e.g., 'en')
+ * @property {string} target - Target locale code (e.g., 'fr')
+ * @property {string} method - Translation method name: 'llm', 'llm-coached', 'google-translate', 'api'
+ * @property {string} model - Model identifier (e.g., 'openai/gpt-4o-mini')
+ * @property {string} qualityTier - Quality tier: 'standard', 'high', 'research', 'verified'
+ * @property {number} batchSize - Max keys per API call
+ * @property {number} maxRetries - Max cascade retries on parse failure
+ * @property {string} register - Translation register / style instruction (resolved prompt text)
+ * @property {string|null} registerPreset - Preset key name (e.g., 'casual-tu') for metadata lookups, or null for custom text
+ * @property {string} name - Human-readable language name (e.g., 'French')
+ * @property {string} dir - Text direction: 'ltr' or 'rtl'
+ * @property {string|null} scripts - LEGACY: the card's scriptConverter key (misleading name, kept for JSON-output compat)
+ * @property {string|null} script - User's `script:` config value (ISO 15924), or null
+ * @property {object|null} scriptFallback - User transliteration rules for unmapped letters ({ sequence: replacement }), or null
+ * @property {{script: string|null, source: string, converterKey: string|null, choices?: Array}} [scriptResolution] - Resolved script decision (set by resolvePairs; see lib/scripts.js resolveTargetScript)
+ * @property {string|null} methodPlugin - Plugin name reference, or null
+ * @property {string|null} formalitySystem - Formality system name (e.g., 'T-V', 'speech-levels'). Used by DeepL for structured formality mapping.
+ * @property {string|null} genderGuidance - Language-specific gender guidance for LLM prompts, or null
+ * @property {Set<string>} _defaults - Fields that were filled from system defaults (used by plugin precedence)
+ *
+ * --- Plugin-injected fields (present after resolvePluginForPair) ---
+ * @property {string} [endpoint] - Plugin API endpoint URL
+ * @property {string} [pluginName] - Installed plugin name
+ * @property {string} [pluginVersion] - Plugin version string
+ * @property {string} [pluginDir] - Absolute path to plugin directory
+ * @property {object|null} [pluginBenchmarks] - Plugin quality benchmarks, or null
+ * @property {object|null} [pluginProvenance] - Plugin provenance/licensing info, or null
+ *
+ * --- Validation thresholds (used by validate.js quality gate) ---
+ * @property {number} [maxLengthRatio] - Max target/source length ratio for validation
+ * @property {number} [minLengthRatio] - Min target/source length ratio for validation
+ * @property {number} [maxRepetitionRate] - Max character repetition rate threshold
+ * @property {boolean} [requireNonLatin] - Whether to require non-Latin script in output
+ */
+
+// -----------------------------------------------------------------
+// LanguageConfig — per-language settings from the user's config
+// Produced by: config.js (from user's `languages` object)
+// Consumed by: pairs.js:resolvePairs()
+// -----------------------------------------------------------------
+
+/**
+ * @typedef {object} LanguageConfig
+ * @property {string} name - Human-readable language name
+ * @property {string} register - Translation register / style instruction (resolved prompt text)
+ * @property {string|null} [registerPreset] - Preset key name for metadata lookups (e.g., DeepL formality), or null for custom text
+ * @property {string} [dir] - Text direction: 'ltr' or 'rtl'
+ * @property {string|null} [formalitySystem] - Formality system name (e.g., 'T-V', 'speech-levels', 'keigo')
+ * @property {string} [model] - Per-language model override
+ * @property {number} [batchSize] - Per-language batch size override
+ * @property {number} [maxRetries] - Per-language max retries override
+ * @property {string} [script] - Script system override (e.g., 'syllabics' for Cree)
+ */
+
+// -----------------------------------------------------------------
+// LanguageCard — unified language metadata from language-cards/*.json
+// Produced by: registers.js:getLanguageCard()
+// Consumed by: config.js, pairs.js, init.js, status.js, deepl.js
+//
+// NOTE (v6 Unified Architecture):
+//   All language data lives in a single card file. The former two-tier
+//   split (v5) is eliminated. getLanguageReference() is a backward-
+//   compat alias for getLanguageCard().
+// -----------------------------------------------------------------
+
+/**
+ * @typedef {object} LanguageCard
+ * @property {string} code - BCP 47 locale code (e.g., 'fr', 'ko', 'x-pirate')
+ * @property {string} name - English language name
+ * @property {string} nativeName - Name in the language itself (e.g., 'Français', '한국어')
+ * @property {string} [iso639_1] - ISO 639-1 two-letter code, or null
+ * @property {string} iso639_3 - ISO 639-3 three-letter code
+ * @property {string} bcp47 - BCP 47 tag
+ * @property {string} script - ISO 15924 script code (e.g., 'Latn', 'Kore', 'Arab')
+ * @property {'ltr'|'rtl'} dir - Text directionality
+ * @property {LanguageFormality|null} formality - Formality system metadata, or null if no system
+ * @property {{ grammatical: boolean, inclusiveGuidance: string|null }} gender - Gender metadata
+ * @property {Object<string, RegisterPreset>} registers - Named register presets
+ * @property {string[]} aliases - Alternative locale codes that resolve to this card
+ * @property {{ googleTranslate: {supported: boolean}, deepl: {supported: boolean, formality?: boolean}, microsoftTranslator: {supported: boolean}, libreTranslate: {supported: boolean}, nllb: {supported: boolean, code?: string}, llm: {supported: boolean} }} methodSupport - API method support — each entry is an object with 'supported' boolean plus optional metadata
+ * @property {string|null} scriptConverter - Script converter reference (e.g., 'serbian-latin-cyrillic')
+ * @property {string[]} evalDatasets - Dataset IDs for the companion eval harness (not consumed by champollion at runtime)
+ * @property {string|null} notes - Free-text notes
+ * @property {object|null} rules - Typography, plurals, capitalization, and variable rules (used by compliance plugin)
+ * @property {{ reviewed: boolean, reviewer?: string, date?: string }|null} [humanReviewed] - Review status
+ * @property {string|null} [glottocode] - Glottolog identifier for family tree cross-referencing
+ * @property {string|null} [extends] - Parent card code for inheritance
+ * @property {string|null} [macrolanguage] - ISO 639-3 macrolanguage umbrella code (e.g., 'cre', 'ara', 'zho')
+ * @property {{ family: string, familyGlottocode: string, genus: string, genusGlottocode: string, ancestry: string[] }|null} [classification] - Genealogical classification from Glottolog + WALS
+ * @property {Array<{ source: string, sourceIso639_3?: string, type: string, domains?: string[], depth: string, period?: string, notes?: string }>|null} [contactInfluences] - Universal contact history
+ * @property {Array<{ code: string, name: string, primary: boolean }>|null} [scripts] - ISO 15924 script tracking
+ * @property {string[]|null} [dataSources] - Provenance tracking (e.g., ['glottolog-5.3', 'cldr-48'])
+ * @property {object|null} [linguisticChallenges] - MT-relevant linguistic challenges
+ * @property {object|null} [encyclopedic] - Language family, demographics, dialect info
+ * @property {object|null} [resources] - NLP corpora, models, FSTs
+ * @property {Array<{ country: string, countryCode: string, officialStatus?: string, region?: string, speakerEstimate?: string, coordinates?: [number, number] }>|null} [regions] - Geographic regions where this language is actively spoken
+ * @property {{ text: string, transliteration?: string, translation: string, literal?: string, source?: string }|null} [culturalAphorism] - Iconic proverb encapsulating the community's worldview
+ */
+
+/**
+ * @typedef {object} LanguageFormality
+ * @property {string} system - Formality system name (e.g., 'T-V', 'speech-levels', 'keigo', 'particles-and-pronouns')
+ * @property {string} description - Human-readable description of how formality works in this language
+ * @property {string} default - Key of the default register preset
+ */
+
+/**
+ * @typedef {object} RegisterPreset
+ * @property {string} label - Display label (e.g., 'Vouvoiement (Formal)', '해요체 (Polite)')
+ * @property {string} description - Short description of when to use this preset
+ * @property {string} prompt - Full register prompt text injected into LLM prompts
+ * @property {string} [deeplFormality] - DeepL API formality value: 'prefer_more', 'prefer_less', or 'default'. Only present on presets for languages where methodSupport.deepl.formality is true.
+ */
+
+// -----------------------------------------------------------------
+// DiffResult — output of comparing source vs target locale
+// Produced by: diff.js:diffLocale()
+// Consumed by: sync.js
+// -----------------------------------------------------------------
+
+/**
+ * @typedef {object} DiffResult
+ * @property {string[]} missing - Keys in source but not in target
+ * @property {string[]} needsTranslation - Keys with [EN] fallback prefix in target
+ * @property {string[]} changed - Keys whose source content hash changed since last sync
+ * @property {string[]} forced - Keys explicitly requested for re-translation
+ * @property {string[]} noTranslate - Exempt keys (config `noTranslate` / auto-detected URL) whose target is not byte-identical to the source and must be copied verbatim. Never translated, gated, or billed.
+ * @property {string[]} extra - Keys in target but not in source (stale/orphaned)
+ * @property {string[]} toProcess - Deduplicated union of missing + needsTranslation + changed + forced, minus every exempt key
+ */
+
+// -----------------------------------------------------------------
+// CoachingData — linguistic coaching hints for LLM-coached method
+// Produced by: llm-coached.js:_loadCoachingData()
+// Consumed by: llm-coached.js:buildCoachedSystemMessage/buildCoachedPrompt
+// -----------------------------------------------------------------
+
+/**
+ * @typedef {object} CoachingData
+ * @property {string[]} [grammar_rules] - Grammar rules (e.g., "French adjectives agree in gender/number")
+ * @property {Object<string, string>} [dictionary] - Term overrides (e.g., "dashboard" → "tableau de bord")
+ * @property {string} [style_notes] - Style guidance (e.g., "Prefer active voice. Avoid anglicisms.")
+ */
+
+// -----------------------------------------------------------------
+// CLI args shape — parsed CLI arguments passed to command modules
+// Produced by: bin/cli.js (util.parseArgs)
+// Consumed by: lib/commands/*.js
+// -----------------------------------------------------------------
+
+/**
+ * @typedef {object} CLIArgs
+ * @property {string[]} [_] - Positional arguments (command, subcommand, etc.)
+ * @property {boolean} [dry] - Preview changes without writing files
+ * @property {boolean} [help] - Show help
+ * @property {boolean} [version] - Show version
+ * @property {boolean} [fallback] - Write [EN]-prefixed placeholders
+ * @property {boolean} [yes] - Skip interactive prompts
+ * @property {boolean} [undo] - Restore from backup (wrap command)
+ * @property {string} [config] - Custom config file path
+ * @property {string} [dir] - Override locales directory
+ * @property {string} [source] - Override source locale
+ * @property {string} [model] - Override translation model
+ * @property {string} [method] - Override translation method
+ * @property {string} [format] - Locale file format override
+ * @property {string} [out] - Output file path (seo sitemap)
+ * @property {string} [src] - Source directory for lint/wrap
+ * @property {string} ['content-dir'] - Hugo content directory
+ * @property {string} ['base-url'] - Site base URL override
+ * @property {string} ['min-length'] - Minimum string length to flag
+ * @property {string} ['force-keys'] - Comma-separated keys to force re-translate
+ * @property {boolean} ['warn-only'] - Exit 0 even with issues
+ */
+
+// Empty export so modules can import types via:
+//   /** @typedef {import('./types.js').PairConfig} PairConfig */
+export {};