champollion 0.3.4 → 0.4.0

package/lib/commands/submit.js

@@ -13,7 +13,7 @@
  *   dataset · resource · method · human-service · external-result · card-correction
  *
  * Interactive wizard when stdin is a TTY; fully scriptable via flags otherwise
- * (--type + --values/--field + --attest, or --yes). See `champollion submit --help`.
+ * (--type + --values/--field + --attest, or --yes). See `champollion network submit --help`.
  *
  * Exit codes: 0 = URL produced (or cancelled); 1 = invalid/incomplete request.
  */
@@ -29,6 +29,7 @@ import {
   resolveType,
   repoBaseFromRepository,
   validateSubmission,
+  normalizeSubmissionValues,
   buildIssueUrl,
   buildSubmissionRecord,
 } from '../submit.mjs';
@@ -181,7 +182,7 @@ async function run(args, cwd) {
       return 0;
     }
     console.log('');
-    console.log('  Submission types (champollion submit --type <key>):');
+    console.log('  Submission types (champollion network submit --type <key>):');
     console.log('');
     SUBMISSION_TYPES.forEach((t, i) => {
       console.log(`    ${i + 1}. ${t.key} — ${t.label}`);
@@ -209,7 +210,7 @@ async function run(args, cwd) {
   } else {
     type = resolveType(args.type);
     if (!type) {
-      output.error('Choose a submission type with --type (run `champollion submit --list`).');
+      output.error('Choose a submission type with --type (run `champollion network submit --list`).');
       return 1;
     }
     values = gatherFromFlags(type, args);
@@ -220,12 +221,16 @@ async function run(args, cwd) {
   if (!v.ok) {
     console.error('[ERR] Cannot build this submission:');
     for (const e of v.errors) console.error(`      • ${e}`);
-    console.error('');
-    console.error('      The compliance attestation is required. Re-run and confirm it');
-    console.error('      (interactively, or pass --attest with the other fields).');
+    if (v.errors.some((e) => e.startsWith('you must confirm'))) {
+      console.error('');
+      console.error('      The compliance attestation is required. Re-run and confirm it');
+      console.error('      (interactively, or pass --attest with the other fields).');
+    }
     return 1;
   }
 
+  // Language pairs go out one way: source>target, one per line (eng-crk in, eng>crk out).
+  values = normalizeSubmissionValues(type, values);
   const issueUrl = buildIssueUrl({ type, values, repoBase });
   const generatedAt = new Date().toISOString();
   const record = buildSubmissionRecord({ type, values, repoBase, generatedAt });
@@ -279,10 +284,10 @@ async function run(args, cwd) {
 
 function showHelp() {
   console.log(`
-  champollion submit — Propose an entry for the Champollion index (review-gated)
+  champollion network submit — Propose an entry for the Champollion index (review-gated)
 
   USAGE
-    champollion submit [options]
+    champollion network submit [options]
 
   DESCRIPTION
     Gather the fields for a submission and print a PRE-FILLED GitHub issue URL
@@ -316,15 +321,15 @@ function showHelp() {
     "${ATTESTATION_TEXT}"
 
   EXAMPLES
-    champollion submit                                   # interactive wizard
-    champollion submit --list                            # see the types
+    champollion network submit                                   # interactive wizard
+    champollion network submit --list                            # see the types
     # A dataset submission, fully from flags:
-    champollion submit --yes --type dataset --attest \\
+    champollion network submit --yes --type dataset --attest \\
       --field dataset-name="GlobalVoices eng-amh" \\
       --field pairs=eng-amh --field license=CC-BY-4.0 \\
       --field source-url=https://globalvoices.org
     # An external result, with a saved local copy:
-    champollion submit --yes --type external-result --attest --out ./submission.json \\
+    champollion network submit --yes --type external-result --attest --out ./submission.json \\
       --values '{"system-name":"NLLB-200","pairs":"eng-crk","dataset":"FLORES-200","metric":"chrF++","score":"28.4","citation":"https://arxiv.org/abs/2207.04672"}'
   `);
 }

package/lib/commands/sync.js

@@ -7,6 +7,7 @@
  */
 
 import { runSync } from '../sync.js';
+import { shutdownMethods } from '../translate.js';
 import { output } from '../output.js';
 
 /**
@@ -20,8 +21,9 @@ import { output } from '../output.js';
  *       totalProcessed > 0`) returned 0 here, so a `sync` wired into a
  *       pre-deploy hook went green while silently shipping English
  *       fallbacks. Any failure with zero progress must be loud.
- *   2 — partial: some keys translated but others failed, OR verification
- *       found errors. The run did real work but isn't clean.
+ *   2 — partial: some keys translated but others failed (or were held
+ *       back: refused before by the same method, so not re-sent), OR
+ *       verification found errors. The run did real work but isn't clean.
  *       ALSO used for a --max-cost abort: the pre-run estimate exceeded the
  *       cap (or was unknowable — unknown ≠ free), so the sync deliberately
  *       stopped BEFORE any API call. Not catastrophic (nothing broke,
@@ -29,7 +31,8 @@ import { output } from '../output.js';
  *
  * Pure and total (never throws) so it can be unit-tested directly.
  *
- * @param {{ totalProcessed?: number, totalFailed?: number, verifyErrors?: number, maxCostAborted?: boolean } | null | undefined} result
+ * @param {{ totalProcessed?: number, totalFailed?: number, totalHeld?: number, contentTranslated?: number, contentFailed?: number,
+ *   contentHeldBack?: number, contentRefused?: number, verifyErrors?: number, maxCostAborted?: boolean } | null | undefined} result
  * @returns {number} exit code
  */
 function computeExitCode(result) {
@@ -38,16 +41,34 @@ function computeExitCode(result) {
   // --max-cost abort: deliberate pre-run stop, exit 2 by documented contract.
   if (result.maxCostAborted) return 2;
 
-  const processed = result.totalProcessed || 0;
-  const failed = result.totalFailed || 0;
+  // A key named for a redo that matches nothing (a typo, a msgid that only
+  // exists with a context): the repair asked for did not happen — exit 1,
+  // never the 0 of a run that "did" nothing.
+  if (Array.isArray(result.unmatchedKeys) && result.unmatchedKeys.length > 0) return 1;
+
+  // Content files count alongside keys: a run where every content file
+  // failed is a failure; one where some failed is partial.
+  const processed = (result.totalProcessed || 0) + (result.contentTranslated || 0);
+  const failed = (result.totalFailed || 0) + (result.contentFailed || 0);
   const verifyErrors = result.verifyErrors || 0;
+  // Keys held back (refused before by this method — lib/locale-state.js):
+  // not translated, so not a clean pass, but nothing failed anew. The same
+  // for Markdown blocks and front-matter fields (lib/content-refusals.js):
+  // held back, or refused by the quality gate this run and left as the
+  // '[EN] ' last resort.
+  // A plural message left without a form the language uses for ordinary
+  // counts (filled with the "other" form, marked in a gettext catalog) is
+  // incomplete in the same way.
+  const held = (result.totalHeld || 0) + (result.contentHeldBack || 0) + (result.contentRefused || 0)
+    + (result.totalPluralGaps || 0);
 
   // Catastrophic: failures with no successful work. A fully-failed sync
   // (bad key, every locale errored) must never exit 0.
   if (failed > 0 && processed === 0) return 1;
 
-  // Partial: real work done but something failed, or files didn't verify.
-  if (failed > 0 || verifyErrors > 0) return 2;
+  // Partial: real work done but something failed or was held back, or
+  // files didn't verify.
+  if (failed > 0 || held > 0 || verifyErrors > 0) return 2;
 
   return 0;
 }
@@ -81,6 +102,9 @@ async function run(args, cwd) {
       return 1;
     }
     throw err;
+  } finally {
+    // Stop the Python bridges external-method pairs started for this run.
+    await shutdownMethods();
   }
 
   return computeExitCode(result);

package/lib/commands/tm.js

@@ -27,11 +27,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
-import { loadTM, saveTM, tmSize, pruneTM, TM_DIR, TM_FILENAME } from '../tm.js';
+import { loadTM, saveTM, tmSize, pruneTM, describeMethodKey, TM_DIR, TM_FILENAME } from '../tm.js';
 import { resolveConfig } from '../config.js';
 import { resolveRuntime } from '../sync.js';
 import { seedTMFromExisting } from '../tm-seed.js';
-import { output } from '../output.js';
+import { output, localTimestamp } from '../output.js';
 
 /**
  * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
@@ -220,6 +220,8 @@ function runStats(args, cwd) {
 
   // Timestamps from metadata
   const created = tm._meta?.created || 'unknown';
+  // JSON keeps the stored (UTC) date for compatibility, plus the full ISO
+  // timestamps; the human report prints local time with the zone named.
   const createdDate = created !== 'unknown' ? created.split('T')[0] : 'unknown';
 
   // Find newest entry timestamp
@@ -277,6 +279,8 @@ function runStats(args, cwd) {
       sizeBytes: stat.size,
       created: createdDate,
       lastEntry: newestDate,
+      createdAt: created !== 'unknown' ? created : null,
+      lastEntryAt: newest || null,
       byLocale,
       unknownLocale: unknownCount,
     }, null, 2));
@@ -286,18 +290,20 @@ function runStats(args, cwd) {
   output.raw('\n  Translation Memory — .champollion/tm.json\n');
   output.raw(`  Entries:      ${entryCount.toLocaleString()}`);
   output.raw(`  File size:    ${sizeStr}`);
-  output.raw(`  Created:      ${createdDate}`);
-  output.raw(`  Last entry:   ${newestDate}`);
+  output.raw(`  Created:      ${created !== 'unknown' ? localTimestamp(created) : 'unknown'}`);
+  output.raw(`  Last entry:   ${newest ? localTimestamp(newest) : 'unknown'}`);
 
   if (sortedLocales.length > 0 || unknownCount > 0) {
     output.raw('\n  By locale:');
 
+    // One line per locale, then what made its entries — method, model and
+    // register in words (the raw cache key "local|stub-1|formal-vous|" was
+    // printed here before; lib/tm.js describeMethodKey).
     for (const [locale, stats] of sortedLocales) {
-      const methodParts = Object.entries(stats.methods)
-        .sort((a, b) => b[1] - a[1])
-        .map(([m, count]) => `${m}: ${count}`);
-      const methodStr = methodParts.length > 0 ? `  (${methodParts.join(', ')})` : '';
-      output.raw(`    ${locale.padEnd(6)} ${String(stats.total).padStart(5)} entries${methodStr}`);
+      output.raw(`    ${locale.padEnd(6)} ${String(stats.total).padStart(5)} entries`);
+      for (const [m, count] of Object.entries(stats.methods).sort((a, b) => b[1] - a[1])) {
+        output.raw(`    ${''.padEnd(6)} ${String(count).padStart(5)}  ${describeMethodKey(m)}`);
+      }
     }
 
     if (unknownCount > 0) {

package/lib/commands/verify.js

@@ -6,14 +6,21 @@
  * success and keys being wrong in fact.
  *
  * Exit code 1 if errors found (CI-gate compatible).
- * --warn-only exits 0 regardless.
+ * --strict exits 1 on warnings too (a source echo, a plural form the
+ * translation did not supply, two locales with identical text, a
+ * translation made from an older source text) — for a CI that must not pass
+ * them. --warn-only exits 0 regardless.
  *
  * This runs the same checks that sync's post-sync verification uses,
  * but can be invoked independently for CI pipelines or manual auditing.
+ *
+ * --pair en:fr (comma-separated) verifies only those pairs' locales — the
+ * same scoping `sync --pair` gives its post-sync verification. An unknown
+ * pair fails loud, exactly as it does for sync.
  */
 
 import { resolveConfig } from '../config.js';
-import { verifyLocales } from '../verify.js';
+import { verifyLocales, localesForPairFlag } from '../verify.js';
 import { output } from '../output.js';
 
 /**
@@ -27,12 +34,29 @@ async function run(args, cwd) {
   if (args.json) output.setMode('json');
   else if (args.quiet) output.setMode('quiet');
 
+  if (args.strict && args['warn-only']) {
+    output.error('--strict (fail on warnings) and --warn-only (never fail) contradict each other — pick one.');
+    return 1;
+  }
   const config = resolveConfig(args, cwd);
-  const { errors } = await verifyLocales(config, cwd);
+  let locales = null;
+  if (args.pair) {
+    try {
+      locales = localesForPairFlag(config, args.pair, { cwd });
+    } catch (err) {
+      output.error(err.message);
+      return 1;
+    }
+  }
+  // --strict: the summary line itself says a warning fails the check.
+  const { errors, warnings } = await verifyLocales(config, cwd, { locales, strict: !!args.strict && !args['warn-only'] });
 
   if (errors > 0 && !args['warn-only']) {
     return 1;
   }
+  if (args.strict && warnings > 0) {
+    return 1;
+  }
   return 0;
 }
 

package/lib/commands/wrap.js

@@ -13,11 +13,12 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveConfig } from '../config.js';
+import { resolveConfig, autoDetectLanguages } from '../config.js';
+import { discoverLocaleLayout } from '../locale-layout.js';
 import { detectFramework, walkDir } from '../lint.js';
 import {
   checkGitClean, createBackup, restoreFromBackup,
-  processFile, generateDiff, addKeysToLocales,
+  processFile, generateDiff, addKeysToLocales, wrapUnsupportedReason,
 } from '../autofix.js';
 import { output } from '../output.js';
 
@@ -54,6 +55,15 @@ async function run(args, cwd) {
   const framework = detectFramework(cwd);
   const minLength = parseInt(args['min-length'] || 2, 10);
 
+  // Decide WHERE extracted keys go before any source file is rewritten — a
+  // wrap that rewrote components to t('…') and then could not store the
+  // keys would leave the app showing raw key names.
+  const destination = resolveWrapDestination(config, cwd);
+  if (destination.error) {
+    output.error(destination.error);
+    return 1;
+  }
+
   output.raw(`\n  champollion wrap${isDry ? ' (dry run)' : ''}`);
   output.raw(`  Framework: ${framework.name}`);
   output.raw('');
@@ -117,9 +127,11 @@ async function run(args, cwd) {
 
   // Add extracted keys to locale files (only if not dry-run)
   if (!isDry && allFixes.length > 0) {
-    const targetLocales = config.languages || [];
-    addKeysToLocales(allFixes, config.localesDir, config.inputLocale, targetLocales);
-    output.info(`Added ${allFixes.length} key(s) to locale files`);
+    const written = addKeysToLocales(allFixes, destination.source, destination.targets);
+    output.info(`Added ${allFixes.length} key(s) to ${destination.source.rel}`
+      + (written.targets > 0 ? ` and ${written.targets} target file(s) (as [EN] placeholders for the next sync)` : ''));
+  } else if (isDry && allFixes.length > 0) {
+    output.info(`Would add ${allFixes.length} key(s) to ${destination.source.rel}`);
   }
 
   output.raw('');
@@ -135,4 +147,50 @@ async function run(args, cwd) {
   return 0;
 }
 
+/**
+ * The locale files `wrap` writes extracted keys into: the source file (one
+ * per flat project; the `defaultNamespace` file — or the only file — of a
+ * folder-per-locale project) and the matching file of every configured
+ * target locale.
+ *
+ * @param {object} config - Resolved config
+ * @param {string} cwd
+ * @returns {{ source?: object, targets?: object[], error?: string }}
+ */
+function resolveWrapDestination(config, cwd) {
+  if (config.format === 'docusaurus') {
+    return { error: 'wrap writes t() keys into key-value locale files; Docusaurus translates through <Translate> and `docusaurus write-translations` — wrap does not apply.' };
+  }
+  const layout = discoverLocaleLayout(config, { cwd });
+  let ns = '';
+  if (layout.namespaced) {
+    const namespaces = layout.sourceFiles.map(f => f.ns);
+    if (config.defaultNamespace) {
+      if (!namespaces.includes(config.defaultNamespace)) {
+        return { error: `"defaultNamespace" is "${config.defaultNamespace}", but the source locale has no such file (namespaces: ${namespaces.join(', ') || 'none'}).` };
+      }
+      ns = config.defaultNamespace;
+    } else if (namespaces.length === 1) {
+      ns = namespaces[0];
+    } else {
+      return { error: `This project has ${namespaces.length} namespace files (${namespaces.join(', ') || 'none'}). `
+        + 'Set "defaultNamespace" in champollion.config.json to choose the file wrap adds keys to.' };
+    }
+  }
+  const source = layout.sourceFiles.find(f => f.ns === ns) || layout.sourceFiles[0];
+  // Flutter ARB and gettext catalogs cannot hold t('dotted.key') keys —
+  // refuse before any component is rewritten.
+  const refusal = source ? wrapUnsupportedReason(source) : null;
+  if (refusal) return { error: refusal };
+  if (!source || !fs.existsSync(source.path)) {
+    return { error: `Source locale file not found: ${source ? source.path : layout.display} — wrap needs it to store the extracted keys.` };
+  }
+  // Configured targets, or — like sync — the ones on disk when none are.
+  const languages = Object.keys(config.resolvedLanguages || {}).length > 0
+    ? config.resolvedLanguages
+    : autoDetectLanguages(config);
+  const targetCodes = Object.keys(languages).filter(c => c !== config.inputLocale);
+  return { source, targets: targetCodes.map(code => layout.fileFor(code, ns)) };
+}
+
 export { run };

package/lib/commands/xliff.js

@@ -20,8 +20,11 @@ import path from 'node:path';
 import { resolveConfig } from '../config.js';
 import { exportXLIFF, importXLIFF } from '../xliff.js';
 import { compileNoTranslate } from '../no-translate.js';
-import { flattenKeys, setNestedValue } from '../flatten.js';
-import { readLocaleFile, writeLocaleFile, detectFormatFromDir, detectYAMLStyle, getExtension } from '../format.js';
+import { setNestedValue, assignInOrder } from '../flatten.js';
+import { writeLocaleFile, detectYAMLStyle } from '../format.js';
+import {
+  discoverLocaleLayout, loadSourceUnits, expectedForTarget, readLocaleFlat, lockKey, splitLockKey,
+} from '../locale-layout.js';
 import { output } from '../output.js';
 
 /** Default output directory for exported XLIFF files */
@@ -75,26 +78,34 @@ function runExport(args, cwd) {
   }
 
   const config = resolveConfig(args, cwd);
-  const format = config.format !== 'auto'
-    ? config.format
-    : detectFormatFromDir(config.localesDir);
-  const ext = getExtension(format);
-
-  // Load source locale
-  const sourcePath = path.join(config.localesDir, `${config.inputLocale}${ext}`);
-  if (!fs.existsSync(sourcePath)) {
-    output.error(`Source locale file not found: ${sourcePath}`);
+  // The project's locale files from the ONE layout module. A folder-per-
+  // locale project exports ALL of a locale's namespace files into one XLIFF
+  // document; unit ids are "<ns>::<key>" (the lock-manifest convention), so
+  // import can route every unit back to its file. Single-file layouts keep
+  // bare keys — their XLIFF is exactly what it was.
+  const layout = discoverLocaleLayout(config, { cwd });
+  const sourceMissing = layout.namespaced
+    ? layout.sourceFiles.length === 0
+    : !fs.existsSync(layout.sourceFiles[0].path);
+  if (sourceMissing) {
+    const where = layout.namespaced ? `${layout.display} (no files for ${config.inputLocale})` : layout.sourceFiles[0].path;
+    output.error(`Source locale file not found: ${where}`);
     return 1;
   }
-  const sourceRaw = readLocaleFile(sourcePath, format);
-  const sourceFlat = format === 'json' ? flattenKeys(sourceRaw) : { ...sourceRaw };
-
-  // Load target locale (may not exist yet — that's fine, all targets will be empty)
-  const targetPath = path.join(config.localesDir, `${locale}${ext}`);
-  let targetFlat = {};
-  if (fs.existsSync(targetPath)) {
-    const targetRaw = readLocaleFile(targetPath, format);
-    targetFlat = format === 'json' ? flattenKeys(targetRaw) : { ...targetRaw };
+  const units = loadSourceUnits(layout);
+
+  // Source = what THIS locale must contain (i18next plurals expand to the
+  // target's own CLDR categories); target = what its files hold today
+  // (files that do not exist yet export as untranslated).
+  const sourceFlat = {};
+  const targetFlat = {};
+  for (const unit of units) {
+    const expected = expectedForTarget(unit, config.inputLocale, locale).flat;
+    for (const [k, v] of Object.entries(expected)) sourceFlat[lockKey(layout, unit.ns, k)] = v;
+    const file = layout.fileFor(locale, unit.ns);
+    if (fs.existsSync(file.path)) {
+      for (const [k, v] of Object.entries(readLocaleFlat(file))) targetFlat[lockKey(layout, unit.ns, k)] = v;
+    }
   }
 
   // Generate XLIFF
@@ -103,8 +114,12 @@ function runExport(args, cwd) {
     targetLocale: locale,
     sourceFlat,
     targetFlat,
-    original: `${config.inputLocale}${ext}`,
-    noTranslate: compileNoTranslate(config),
+    original: layout.namespaced
+      ? (layout.kind === 'dir' ? `${config.inputLocale}/` : layout.display)
+      : units[0].file.rel,
+    // No-translate patterns match a key WITHIN its file — strip the
+    // namespace before asking.
+    noTranslate: namespacedMatcher(compileNoTranslate(config), layout),
   });
 
   // Determine output path
@@ -198,42 +213,69 @@ function runImport(args, cwd) {
   }
 
   const config = resolveConfig(args, cwd);
-  const format = config.format !== 'auto'
-    ? config.format
-    : detectFormatFromDir(config.localesDir);
-  const ext = getExtension(format);
-  const targetPath = path.join(config.localesDir, `${locale}${ext}`);
+  const layout = discoverLocaleLayout(config, { cwd });
 
   const dryRun = args.dry || false;
 
-  // Load existing target locale (or start fresh)
-  let existingFlat = {};
-  let existingRaw = {};
-  if (fs.existsSync(targetPath)) {
-    existingRaw = readLocaleFile(targetPath, format);
-    existingFlat = format === 'json' ? flattenKeys(existingRaw) : { ...existingRaw };
+  // Route every unit to its file. Namespaced layouts need "<ns>::<key>" ids
+  // (what `xliff export` writes); an id without one — or naming a namespace
+  // the source does not have — fails the whole import before anything is
+  // written, rather than guessing a file.
+  const byNs = new Map();
+  const unroutable = [];
+  const knownNs = new Set(layout.sourceFiles.map(f => f.ns));
+  for (const [id, value] of Object.entries(translations)) {
+    const parts = splitLockKey(layout, id);
+    if (!parts || (layout.namespaced && knownNs.size > 0 && !knownNs.has(parts.ns))) {
+      unroutable.push(id);
+      continue;
+    }
+    if (!byNs.has(parts.ns)) byNs.set(parts.ns, {});
+    byNs.get(parts.ns)[parts.key] = value;
+  }
+  if (unroutable.length > 0) {
+    // A gettext context key prints its U+0004 as "␄", as it was exported.
+    const sample = unroutable.slice(0, 5).map(id => id.replace(/\u0004/g, '\u2404')).join(', ');
+    output.error(
+      `${unroutable.length} XLIFF unit id(s) do not name one of this project's locale files: ${sample}`
+      + `${unroutable.length > 5 ? ', …' : ''}. In a folder-per-locale project ids are "<namespace>::<key>" `
+      + `(namespaces: ${[...knownNs].join(', ') || 'none found'}) — export with \`champollion xliff export\`.`);
+    return 1;
   }
 
-  // Merge: XLIFF translations overwrite existing values
+  // Merge: XLIFF translations overwrite existing values, file by file.
   let updated = 0;
   let added = 0;
-  for (const [key, value] of Object.entries(translations)) {
-    if (key in existingFlat) {
-      if (existingFlat[key] !== value) {
-        updated++;
+  const writes = [];
+  for (const [ns, entries] of byNs) {
+    const file = layout.fileFor(locale, ns);
+    const existingFlat = fs.existsSync(file.path) ? readLocaleFlat(file) : {};
+    for (const [key, value] of Object.entries(entries)) {
+      if (key in existingFlat) {
+        if (existingFlat[key] !== value) {
+          updated++;
+        }
+      } else {
+        added++;
       }
-    } else {
-      added++;
+      // A plural form new to the file goes beside its siblings in CLDR order.
+      assignInOrder(existingFlat, key, value);
     }
-    existingFlat[key] = value;
+    writes.push({ ns, file, existingFlat });
   }
 
   const skipped = Object.keys(translations).length - updated - added;
+  // One file: report its path as before. Several: the layout's pattern.
+  const targetPath = writes.length === 1 ? writes[0].file.path : layout.filesFor(locale)[0]?.path || layout.baseDir;
+  const targetLabel = writes.length === 1
+    ? path.relative(cwd, writes[0].file.path)
+    : `${writes.length} files (${writes.map(w => w.file.rel).join(', ')})`;
 
   if (dryRun) {
     if (args.json) {
       console.log(JSON.stringify({
         command: 'xliff', action: 'import', dryRun: true, locale, path: targetPath,
+        ...(writes.length > 1 && { files: writes.map(w => w.file.path) }),
         imported: Object.keys(translations).length, updated, added, unchanged: skipped,
       }, null, 2));
       return 0;
@@ -242,38 +284,48 @@ function runImport(args, cwd) {
     output.raw(`    Updated:  ${updated} (changed from existing)`);
     output.raw(`    Added:    ${added} (new keys)`);
     output.raw(`    Unchanged: ${skipped}`);
-    output.raw(`    Target:   ${path.relative(cwd, targetPath)}\n`);
+    output.raw(`    Target:   ${targetLabel}\n`);
     return 0;
   }
 
   // Write back
-  if (format === 'json') {
-    // Re-nest the flat map into JSON structure using setNestedValue
-    const nested = {};
-    for (const [key, value] of Object.entries(existingFlat)) {
-      setNestedValue(nested, key, value);
-    }
-    fs.writeFileSync(targetPath, JSON.stringify(nested, null, 2) + '\n', 'utf-8');
-  } else {
-    // TOML/YAML — write the merged flat map back through the exact same
-    // writer sync uses (lib/format.js writeLocaleFile), so an imported file
-    // keeps the serialization style of a synced project. YAML needs the
-    // style probe sync performs on the SOURCE locale file (Hugo plural
-    // sub-keys vs standard nesting); fall back to the target file when the
-    // source is missing.
-    let yamlStyle = null;
-    if (format === 'yaml') {
-      const sourcePath = path.join(config.localesDir, `${config.inputLocale}${ext}`);
-      const stylePath = fs.existsSync(sourcePath) ? sourcePath
-        : (fs.existsSync(targetPath) ? targetPath : null);
-      yamlStyle = stylePath ? detectYAMLStyle(fs.readFileSync(stylePath, 'utf-8')) : null;
+  for (const { ns, file, existingFlat } of writes) {
+    fs.mkdirSync(path.dirname(file.path), { recursive: true });
+    if (file.format === 'json') {
+      // Re-nest the flat map into JSON structure using setNestedValue
+      const nested = {};
+      for (const [key, value] of Object.entries(existingFlat)) {
+        setNestedValue(nested, key, value);
+      }
+      fs.writeFileSync(file.path, JSON.stringify(nested, null, 2) + '\n', 'utf-8');
+    } else {
+      // TOML/YAML — write the merged flat map back through the exact same
+      // writer sync uses (lib/format.js writeLocaleFile), so an imported file
+      // keeps the serialization style of a synced project. YAML needs the
+      // style probe sync performs on the SOURCE locale file (Hugo plural
+      // sub-keys vs standard nesting); fall back to the target file when the
+      // source is missing.
+      let yamlStyle = null;
+      if (file.format === 'yaml') {
+        const sourcePath = layout.sourceFiles.find(f => f.ns === ns)?.path;
+        const stylePath = sourcePath && fs.existsSync(sourcePath) ? sourcePath
+          : (fs.existsSync(file.path) ? file.path : null);
+        yamlStyle = stylePath ? detectYAMLStyle(fs.readFileSync(stylePath, 'utf-8')) : null;
+      }
+      // Document formats (.po, .arb) are rebuilt from the SOURCE file's
+      // structure — plural entries, metadata, @@locale — not from the flat
+      // map alone (a brand-new target has no structure of its own).
+      writeLocaleFile(file.path, existingFlat, file.format, existingFlat, yamlStyle, {
+        sourcePath: file.sourcePath || null,
+        locale: file.code || null,
+      });
     }
-    writeLocaleFile(targetPath, existingFlat, format, existingFlat, yamlStyle);
   }
 
   if (args.json) {
     console.log(JSON.stringify({
       command: 'xliff', action: 'import', dryRun: false, locale, path: targetPath,
+      ...(writes.length > 1 && { files: writes.map(w => w.file.path) }),
       imported: Object.keys(translations).length, updated, added, unchanged: skipped,
     }, null, 2));
     return 0;
@@ -283,11 +335,30 @@ function runImport(args, cwd) {
   output.raw(`    Updated:    ${updated} (changed from existing)`);
   output.raw(`    Added:      ${added} (new keys)`);
   output.raw(`    Unchanged:  ${skipped}`);
-  output.raw(`    Written to: ${path.relative(cwd, targetPath)}\n`);
+  output.raw(`    Written to: ${targetLabel}\n`);
 
   return 0;
 }
 
+/**
+ * Wrap a no-translate matcher so it receives the key WITHIN its file:
+ * patterns are written against a file's own keys ("**.url"), never against
+ * the "<ns>::" prefix the XLIFF ids carry.
+ *
+ * @param {import('../no-translate.js').NoTranslateMatcher} matcher
+ * @param {{ namespaced: boolean }} layout
+ */
+function namespacedMatcher(matcher, layout) {
+  if (!layout.namespaced) return matcher;
+  return {
+    ...matcher,
+    matches: (id, value) => {
+      const parts = splitLockKey(layout, id);
+      return matcher.matches(parts ? parts.key : id, value);
+    },
+  };
+}
+
 // -----------------------------------------------------------------
 // Usage
 // -----------------------------------------------------------------