champollion 0.3.4 → 0.4.0

package/lib/format.js

@@ -1,5 +1,6 @@
 /**
- * Format adapter — reads and writes locale files in JSON, TOML, and YAML.
+ * Format adapter — reads and writes locale files in JSON, TOML, YAML,
+ * gettext PO/POT (lib/po.js) and Flutter ARB.
  *
  * WHY: Hugo uses TOML or YAML for i18n string files, not JSON.
  * Hugo's i18n/ structure looks like:
@@ -20,10 +21,20 @@
  */
 
 import fs from 'node:fs';
+import path from 'node:path';
+import { readPO, writePO, emptyPO } from './po.js';
 
 // CLDR plural categories used by Hugo/go-i18n
 const PLURAL_FORMS = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
 
+/**
+ * Key-value locale formats this module can READ and WRITE. The single list
+ * config validation (lib/config.js) and the layout reader
+ * (lib/locale-layout.js) check against — a format added to
+ * readLocaleFile/writeLocaleFile is added here, and nowhere else.
+ */
+const LOCALE_FILE_FORMATS = Object.freeze(['json', 'toml', 'yaml', 'po', 'arb']);
+
 /**
  * Strip a leading UTF-8 BOM (U+FEFF) from a decoded string.
  *
@@ -48,23 +59,27 @@ function stripBOM(str) {
  * Detect the locale file format from a file path's extension.
  *
  * @param {string} filePath - Path to a locale file
- * @returns {'json'|'toml'|'yaml'} Detected format
+ * @returns {'json'|'toml'|'yaml'|'po'|'arb'} Detected format
  */
 function detectFormat(filePath) {
   if (filePath.endsWith('.toml')) return 'toml';
   if (filePath.endsWith('.yaml') || filePath.endsWith('.yml')) return 'yaml';
+  if (filePath.endsWith('.po') || filePath.endsWith('.pot')) return 'po';
+  if (filePath.endsWith('.arb')) return 'arb';
   return 'json';
 }
 
 /**
  * Get the file extension string for a format.
  *
- * @param {'json'|'toml'|'yaml'} format
+ * @param {'json'|'toml'|'yaml'|'po'|'arb'} format
  * @returns {string} File extension including the dot
  */
 function getExtension(format) {
   if (format === 'toml') return '.toml';
   if (format === 'yaml') return '.yaml';
+  if (format === 'po') return '.po';
+  if (format === 'arb') return '.arb';
   return '.json';
 }
 
@@ -72,21 +87,30 @@ function getExtension(format) {
  * Auto-detect the format used in a locales directory by scanning
  * for the most common file extension present.
  *
+ * Ties keep the historical preference: json, then toml, then yaml; the
+ * gettext (.po/.pot) and ARB counts only win outright.
+ *
  * @param {string} localesDir - Path to the locales directory
- * @returns {'json'|'toml'|'yaml'} Detected format, defaults to 'json'
+ * @returns {'json'|'toml'|'yaml'|'po'|'arb'} Detected format, defaults to 'json'
  */
 function detectFormatFromDir(localesDir) {
   if (!fs.existsSync(localesDir)) return 'json';
 
   const files = fs.readdirSync(localesDir);
-  const counts = { json: 0, toml: 0, yaml: 0 };
+  const counts = { json: 0, toml: 0, yaml: 0, po: 0, arb: 0 };
 
   for (const file of files) {
     if (file.endsWith('.toml')) counts.toml++;
     else if (file.endsWith('.yaml') || file.endsWith('.yml')) counts.yaml++;
     else if (file.endsWith('.json')) counts.json++;
+    else if (file.endsWith('.po') || file.endsWith('.pot')) counts.po++;
+    else if (file.endsWith('.arb')) counts.arb++;
   }
 
+  const classic = Math.max(counts.json, counts.toml, counts.yaml);
+  if (counts.po > classic && counts.po >= counts.arb) return 'po';
+  if (counts.arb > classic && counts.arb > counts.po) return 'arb';
+
   // Return whichever format has the most files
   if (counts.toml > counts.json && counts.toml >= counts.yaml) return 'toml';
   if (counts.yaml > counts.json && counts.yaml >= counts.toml) return 'yaml';
@@ -104,11 +128,22 @@ function detectFormatFromDir(localesDir) {
  * { "key": "value" }. Plural keys flatten to { "key.one": "...",
  * "key.other": "..." }.
  *
+ * gettext (po): keys are msgids (`msgctxt\u0004msgid` with a context),
+ * plural entries are ICU plural messages — see lib/po.js. A SOURCE catalog
+ * (role 'source': a .pot or the source-language .po) yields msgid where
+ * msgstr is empty; a target yields only translated, non-fuzzy entries.
+ *
+ * ARB (Flutter): the translatable messages only — `@@locale` and every
+ * `@key` metadata object are never part of the map.
+ *
  * @param {string} filePath - Path to the locale file
- * @param {'json'|'toml'|'yaml'} format - File format
+ * @param {'json'|'toml'|'yaml'|'po'|'arb'} format - File format
+ * @param {{ role?: 'source'|'target', locale?: string|null }} [options] -
+ *   gettext only: which side of the catalog is read, and its locale (for
+ *   mapping msgstr[i] onto plural categories)
  * @returns {object} Flat key→value map
  */
-function readLocaleFile(filePath, format) {
+function readLocaleFile(filePath, format, options = {}) {
   if (!fs.existsSync(filePath)) return {};
   // Strip a leading BOM before any parsing — a U+FEFF prefix otherwise
   // hard-crashes JSON.parse() and silently breaks the first key match in
@@ -118,6 +153,10 @@ function readLocaleFile(filePath, format) {
 
   if (format === 'toml') return parseTOMLToFlat(raw);
   if (format === 'yaml') return parseYAMLToFlat(raw);
+  if (format === 'po') {
+    return readPO(raw, { role: options.role || 'target', locale: options.locale || null, filePath }).flat;
+  }
+  if (format === 'arb') return arbMessages(parseARB(raw, filePath), filePath);
 
   // JSON: caller handles flattening. Wrap the raw V8 SyntaxError (which only
   // gives a byte offset, no filename or hint) in a file-named, friendlier
@@ -220,15 +259,43 @@ function findDuplicateJSONKeys(raw) {
  * For JSON, this writes the nested structure directly.
  * For TOML/YAML, this converts to the appropriate section format.
  *
+ * gettext and ARB files are DOCUMENTS, not maps: the writer rebuilds them
+ * around the flat map from a template — the source file named by
+ * `options.sourcePath` (its entry/key order, its metadata) — and the
+ * existing target (untouched entries kept byte for byte, translator
+ * comments, header). Without a sourcePath the existing file is its own
+ * template (xliff import, autofix).
+ *
  * @param {string} filePath - Output file path
- * @param {object} data - Nested data object (for JSON) or flat map (for TOML/YAML)
- * @param {'json'|'toml'|'yaml'} format - Target format
- * @param {object} flatData - Flat key→value map (used for TOML/YAML reconstruction)
+ * @param {object} data - Nested data object (for JSON) or flat map (for TOML/YAML/po/arb)
+ * @param {'json'|'toml'|'yaml'|'po'|'arb'} format - Target format
+ * @param {object} flatData - Flat key→value map (used for non-JSON reconstruction)
  * @param {'hugo'|'nested'|null} yamlStyle - YAML variant: 'hugo' for Hugo i18n, 'nested' for standard nested YAML
+ * @param {{ sourcePath?: string|null, locale?: string|null }} [options] -
+ *   po/arb: the source (template) file and the locale being written
  */
-function writeLocaleFile(filePath, data, format, flatData, yamlStyle) {
+function writeLocaleFile(filePath, data, format, flatData, yamlStyle, options = {}) {
   let content;
-  if (format === 'toml') {
+  if (format === 'po' || format === 'arb') {
+    const readIfExists = (p) => (p && fs.existsSync(p) ? stripBOM(fs.readFileSync(p, 'utf-8')) : null);
+    const targetText = readIfExists(filePath);
+    const sourcePath = options.sourcePath && options.sourcePath !== filePath ? options.sourcePath : null;
+    const sourceText = readIfExists(sourcePath);
+    const flat = flatData || data;
+    if (format === 'po') {
+      content = writePO({
+        flat, sourceText, targetText: targetText && targetText.trim() ? targetText : null,
+        locale: options.locale || null, filePath, projectName: projectNameForHeader(),
+      });
+    } else {
+      content = serializeARB({
+        flat,
+        sourceDoc: sourceText && sourceText.trim() ? parseARB(sourceText, sourcePath) : null,
+        targetDoc: targetText && targetText.trim() ? parseARB(targetText, filePath) : null,
+        locale: options.locale || null,
+      });
+    }
+  } else if (format === 'toml') {
     content = flatToTOML(flatData || data);
   } else if (format === 'yaml') {
     // Route to the correct YAML serializer based on detected style.
@@ -796,6 +863,185 @@ function groupFlatKeys(flat) {
   return sections;
 }
 
+// -----------------------------------------------------------------
+// Flutter ARB
+//
+//   {
+//     "@@locale": "en",
+//     "itemCount": "{count, plural, =0{No items} one{1 item} other{{count} items}}",
+//     "@itemCount": { "description": "…", "placeholders": { "count": { "type": "int" } } }
+//   }
+//
+// Only the messages are translatable. `@@locale` names the file's locale
+// (gen-l10n refuses a file whose @@locale disagrees with its name), every
+// `@key` object is code metadata — placeholder names and Dart types — and
+// translating either breaks the build. So the reader never returns them,
+// and the writer sets `@@locale` to the TARGET locale (Flutter's
+// underscore form, as in the file name) and copies each message's metadata
+// from the source (or keeps the target's, for a key the source has none
+// for). Key order follows the source.
+// -----------------------------------------------------------------
+
+/**
+ * Parse an .arb file with a file-named error.
+ *
+ * @param {string} raw
+ * @param {string} filePath
+ * @returns {object}
+ */
+function parseARB(raw, filePath) {
+  let doc;
+  try {
+    doc = JSON.parse(stripBOM(raw));
+  } catch (err) {
+    throw new Error(`Invalid ARB (JSON) in ${filePath}: ${err.message}`);
+  }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new Error(`Invalid ARB in ${filePath}: the top level must be a JSON object.`);
+  }
+  for (const dup of findDuplicateJSONKeys(raw)) {
+    console.warn(`  [WARN] Duplicate ARB key "${dup}" in ${filePath} — later value wins, earlier value discarded.`);
+  }
+  return doc;
+}
+
+/** The translatable messages of an ARB document. */
+function arbMessages(doc, filePath = '') {
+  const flat = {};
+  for (const [key, value] of Object.entries(doc)) {
+    if (key.startsWith('@')) continue;
+    if (typeof value === 'string') flat[key] = value;
+    else console.warn(`  [WARN] ${filePath}: ARB message "${key}" is not a string — not translated.`);
+  }
+  return flat;
+}
+
+/** Flutter writes locales with underscores (app_pt_BR.arb, "@@locale": "pt_BR"). */
+function flutterLocale(code) {
+  return String(code).replace(/-/g, '_');
+}
+
+/**
+ * Serialize a target ARB document.
+ *
+ * @param {object} options
+ * @param {object} options.flat - Messages (key → text)
+ * @param {object|null} options.sourceDoc - Parsed source ARB (template)
+ * @param {object|null} options.targetDoc - Parsed existing target ARB
+ * @param {string|null} options.locale - Target locale code
+ * @returns {string}
+ */
+function serializeARB({ flat, sourceDoc, targetDoc, locale }) {
+  const out = {};
+  const has = (doc, key) => !!doc && Object.prototype.hasOwnProperty.call(doc, key);
+  const loc = locale ? flutterLocale(locale)
+    : (has(targetDoc, '@@locale') ? targetDoc['@@locale'] : (has(sourceDoc, '@@locale') ? sourceDoc['@@locale'] : null));
+  if (loc !== null && loc !== undefined) out['@@locale'] = loc;
+  const done = new Set(['@@locale']);
+
+  const emitMessage = (key) => {
+    if (done.has(key) || typeof flat[key] !== 'string') return;
+    out[key] = flat[key];
+    done.add(key);
+    const meta = `@${key}`;
+    if (has(sourceDoc, meta)) out[meta] = sourceDoc[meta];
+    else if (has(targetDoc, meta)) out[meta] = targetDoc[meta];
+    done.add(meta);
+  };
+  const emitGlobal = (key, fromDoc) => {
+    if (done.has(key)) return;
+    out[key] = has(targetDoc, key) ? targetDoc[key] : fromDoc[key];
+    done.add(key);
+  };
+
+  const template = sourceDoc || targetDoc || {};
+  for (const key of Object.keys(template)) {
+    if (key.startsWith('@@')) emitGlobal(key, template);
+    else if (!key.startsWith('@')) emitMessage(key);
+  }
+  // Messages the target has and the source does not (kept, with their
+  // metadata), then anything else the caller added.
+  for (const key of Object.keys(targetDoc || {})) {
+    if (key.startsWith('@@')) emitGlobal(key, targetDoc);
+    else if (!key.startsWith('@')) emitMessage(key);
+  }
+  for (const key of Object.keys(flat)) {
+    if (!key.startsWith('@')) emitMessage(key);
+  }
+  return JSON.stringify(out, null, 2) + '\n';
+}
+
+/**
+ * The content of a new, empty target file in a document format, or null
+ * for a format whose empty file is not special.
+ *
+ * @param {string} format
+ * @param {string} locale
+ * @param {{ sourcePath?: string|null }} [options] - po: the template the
+ *   new catalog mirrors (its header fields are carried over)
+ * @returns {string|null}
+ */
+function emptyDocumentContent(format, locale, { sourcePath = null } = {}) {
+  if (format === 'arb') return JSON.stringify({ '@@locale': flutterLocale(locale) }, null, 2) + '\n';
+  if (format === 'po') {
+    const sourceText = sourcePath && fs.existsSync(sourcePath) ? stripBOM(fs.readFileSync(sourcePath, 'utf-8')) : null;
+    return emptyPO(locale, { sourceText: sourceText && sourceText.trim() ? sourceText : null, projectName: projectNameForHeader() });
+  }
+  return null;
+}
+
+/**
+ * A new gettext catalog's Project-Id-Version when its template has only
+ * xgettext's "PACKAGE VERSION": the project folder's name, as msginit
+ * writes (lib/po.js newHeaderFields). Commands run from the project root.
+ */
+function projectNameForHeader() {
+  return path.basename(process.cwd()) || null;
+}
+
+/**
+ * Per-key translator context a SOURCE file carries for the prompt: ARB
+ * `@key.description`, gettext msgctxt and `#.` extracted comments. Other
+ * formats carry none.
+ *
+ * @param {string} filePath
+ * @param {string} format
+ * @returns {object} key → description
+ */
+function readLocaleContext(filePath, format) {
+  if (!fs.existsSync(filePath)) return {};
+  const raw = stripBOM(fs.readFileSync(filePath, 'utf-8'));
+  if (!raw.trim()) return {};
+  if (format === 'po') return readPO(raw, { role: 'source', filePath }).context;
+  if (format === 'arb') {
+    const doc = parseARB(raw, filePath);
+    const out = {};
+    for (const [key, value] of Object.entries(doc)) {
+      if (key.startsWith('@') || typeof value !== 'string') continue;
+      const meta = doc[`@${key}`];
+      if (meta && typeof meta === 'object' && typeof meta.description === 'string' && meta.description.trim()) {
+        out[key] = meta.description.trim();
+      }
+    }
+    return out;
+  }
+  return {};
+}
+
+/**
+ * The `@@locale` an ARB file declares, or undefined when it has none.
+ *
+ * @param {string} filePath
+ * @returns {string|undefined}
+ */
+function readARBLocale(filePath) {
+  if (!fs.existsSync(filePath)) return undefined;
+  const raw = stripBOM(fs.readFileSync(filePath, 'utf-8'));
+  if (!raw.trim()) return undefined;
+  const doc = parseARB(raw, filePath);
+  return Object.prototype.hasOwnProperty.call(doc, '@@locale') ? doc['@@locale'] : undefined;
+}
+
 // -----------------------------------------------------------------
 // Docusaurus format helpers
 //
@@ -931,6 +1177,7 @@ function injectDocusaurusMessages(sourceData, translatedFlat) {
 }
 
 export {
+  LOCALE_FILE_FORMATS,
   detectFormat,
   detectFormatFromDir,
   getExtension,
@@ -950,5 +1197,12 @@ export {
   extractDocusaurusMessages,
   extractDocusaurusDescriptions,
   injectDocusaurusMessages,
+  parseARB,
+  arbMessages,
+  serializeARB,
+  flutterLocale,
+  emptyDocumentContent,
+  readLocaleContext,
+  readARBLocale,
 };
 

package/lib/hash.js

@@ -15,15 +15,62 @@
  *   content mutations. This hash layer closes that gap automatically.
  *
  * FILE FORMAT:
- *   .champollion.lock is a JSON file mapping dot-notation keys to
- *   their SHA-256 hash. It should be committed to version control so
- *   that all developers and CI share the same baseline.
+ *   .champollion.lock is JSON, committed to version control so that all
+ *   developers and CI share the same baseline. Version 1 (every lock before
+ *   0.4.0, and still what a project with no per-locale record writes) maps
+ *   each source key to the SHA-256 of its source text:
+ *
+ *   { "nav.home": "a1b2c3...", "nav.about": "d4e5f6..." }
+ *
+ *   Version 2 nests that map under "source" and adds what sync knows per
+ *   target locale (lib/locale-state.js):
  *
  *   {
- *     "nav.home": "a1b2c3...",
- *     "nav.about": "d4e5f6...",
- *     ...
+ *     "version": 2,
+ *     "source": { "nav.home": "a1b2c3..." },
+ *     "locales": {
+ *       "fr": {
+ *         "written": { "nav.home": "<12 hex of the source>:<12 hex of the value>" },
+ *         "pending": { "nav.about": "--redo all --fresh-on-model-change" },
+ *         "refused": { "nav.cta": { "source": "<12 hex>", "methods": ["llm|m|formal|"], "on": "2026-10-03" } },
+ *         "forms": { "items_many": "many:<12 hex of the value>" },
+ *         "gaps": { "files": { "source": "<12 hex>", "methods": ["local|stub-1|formal|"] } },
+ *         "by": { "llm|google/gemini-3.5-flash|formal|": ["nav.home"] }
+ *       }
+ *     }
  *   }
+ *
+ *   written — the value sync left in the file for each key and the source
+ *             text it translated: a value that no longer matches was edited
+ *             by hand; a source that no longer matches means the translation
+ *             is out of date.
+ *   pending — keys a redo (--redo all, --redo keys:, a model switch) could not
+ *             finish; the next plain sync asks for them once more.
+ *   refused — keys whose current source text the quality gate refused from
+ *             these methods; a plain sync does not send them to the same
+ *             method again (it would bill the same answer).
+ *   forms   — borrowed i18next plural forms (French `items_many`, translated
+ *             from the English `items_other` text) the model was asked for AS
+ *             that form, with the fingerprint of the value its answer left.
+ *             verify reads it to tell "the model wrote `_many` like `_other`"
+ *             from "filled from `_other`" using committed files only. Older
+ *             versions of the CLI ignore it.
+ *   gaps    — plural messages a setup (method key) answered without a form
+ *             the language uses for ordinary counts, per current source text:
+ *             a sync with another setup asks for them again, and one that
+ *             already tried does not (lib/plural-gap-redo.js). Written only
+ *             when there is one; older versions of the CLI ignore it.
+ *   by      — which method key (method|model|register|coaching) produced the
+ *             value `written` records for each key — the model that answered,
+ *             or the one whose cache entry served it. `status` names the
+ *             model behind the files from it; a value with no `by` (written
+ *             before 0.4.0) is attributed from the cache, or "model unknown"
+ *             when several models cached the same text. Older versions of
+ *             the CLI ignore it.
+ *
+ *   readManifest() returns the source map for either version, so every
+ *   reader of "which source changed" is unchanged; writeManifest() keeps the
+ *   per-locale part of an existing lock unless it is given a new one.
  */
 
 import crypto from 'node:crypto';
@@ -97,35 +144,79 @@ function detectChangedKeys(sourceFlat, oldManifest) {
  * @returns {object} Hash manifest (key → hash), or {} if no lock file
  */
 function readManifest(cwd) {
+  return readLock(cwd).source;
+}
+
+/** Lock format written when there is per-locale state to record. */
+const LOCK_VERSION = 2;
+
+/**
+ * Split parsed lock JSON into its source map and per-locale state.
+ * Version 1 (a flat key → hash map) has no per-locale state.
+ *
+ * @param {*} data - Parsed .champollion.lock
+ * @returns {{ source: object, locales: object }}
+ */
+function splitLock(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error('not a JSON object');
+  }
+  // Version 2 is recognised by its shape: a v1 lock maps keys to hash
+  // STRINGS, so a numeric "version" next to an object "source" cannot be one.
+  if (typeof data.version === 'number' && data.source && typeof data.source === 'object' && !Array.isArray(data.source)) {
+    if (data.version > LOCK_VERSION) {
+      throw new Error(`written by a newer champollion (lock version ${data.version}; this version reads up to ${LOCK_VERSION}) — upgrade champollion`);
+    }
+    const locales = data.locales && typeof data.locales === 'object' && !Array.isArray(data.locales) ? data.locales : {};
+    return { source: { ...data.source }, locales };
+  }
+  return { source: { ...data }, locales: {} };
+}
+
+/**
+ * Read the whole lock: the source-hash map and the per-locale state
+ * (lib/locale-state.js). Fails loud on an unreadable file, like readManifest.
+ *
+ * @param {string} cwd - Project root directory
+ * @returns {{ source: object, locales: object, exists: boolean }}
+ */
+function readLock(cwd) {
   const lockPath = path.join(cwd, LOCK_FILENAME);
 
   if (!fs.existsSync(lockPath)) {
-    return {};
+    return { source: {}, locales: {}, exists: false };
   }
 
   try {
-    return JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+    return { ...splitLock(JSON.parse(fs.readFileSync(lockPath, 'utf-8'))), exists: true };
   } catch (err) {
     // FAIL LOUD. Returning {} means "no key has ever been synced", so the
     // very next sync treats every key as changed and re-translates the whole
     // project at full API cost. A `[WARN]` that says "it will be regenerated"
     // reads as routine housekeeping and gives no hint of that bill.
+    // Treating it as missing loses track of which translations are out of
+    // date: nothing counts as changed (detectChangedKeys needs an old hash),
+    // so every existing translation is kept even where its source moved.
+    // (An earlier message claimed the opposite — a full re-translation —
+    // which is not what the code does.)
     if (process.env.CHAMPOLLION_ALLOW_CACHE_RESET === '1') {
       console.error(
         `[WARN] ${LOCK_FILENAME} is unreadable (${err.message}). `
-        + `CHAMPOLLION_ALLOW_CACHE_RESET=1 — treating this as a first run; `
-        + `every key will be re-translated at full cost.`,
+        + `CHAMPOLLION_ALLOW_CACHE_RESET=1 — treating it as missing: missing keys are `
+        + `translated, but translations whose source changed are NOT detected this run. `
+        + `Use \`champollion sync --redo all\` to rebuild (cached text is free).`,
       );
-      return {};
+      return { source: {}, locales: {}, exists: false };
     }
     const e = new Error(
       `Lock file is unreadable: ${err.message}\n\n`
       + `  ${lockPath}\n\n`
-      + `Refusing to continue: treating this as a first run would mark every `
-      + `key as changed and re-translate the whole project at full API cost.\n\n`
+      + `Refusing to continue: without it, sync cannot tell which existing `
+      + `translations are out of date, and would silently keep stale ones.\n\n`
       + `  • Restore the file from version control if you can, or\n`
-      + `  • delete it and re-run to accept the re-translation cost, or\n`
-      + `  • re-run with CHAMPOLLION_ALLOW_CACHE_RESET=1 to do that in place.`,
+      + `  • delete it and run \`champollion sync --redo all\` once (cached `
+      + `translations are served free; only text the cache has never seen is billed), or\n`
+      + `  • re-run with CHAMPOLLION_ALLOW_CACHE_RESET=1 to continue without it.`,
     );
     e.code = 'CHAMPOLLION_LOCK_UNREADABLE';
     throw e;
@@ -136,17 +227,49 @@ function readManifest(cwd) {
  * Write the hash manifest to disk.
  * Sorts keys alphabetically for stable, diff-friendly output.
  *
+ * The per-locale state (lib/locale-state.js) is written alongside when there
+ * is any: `locales` replaces it; omitted, the state already in the lock is
+ * kept (the Docusaurus path writes only source hashes). With no per-locale
+ * state the file stays in the version-1 flat form, byte for byte.
+ *
  * @param {string} cwd - Project root directory
  * @param {object} manifest - Hash manifest (key → hash)
+ * @param {object} [locales] - Per-locale state to record (see the header)
  */
-function writeManifest(cwd, manifest) {
+function writeManifest(cwd, manifest, locales = undefined) {
   const lockPath = path.join(cwd, LOCK_FILENAME);
-  // Sort keys for deterministic output — makes git diffs clean
-  const sorted = {};
-  for (const key of Object.keys(manifest).sort()) {
-    sorted[key] = manifest[key];
+  let state = locales;
+  if (state === undefined) {
+    try {
+      state = fs.existsSync(lockPath) ? splitLock(JSON.parse(fs.readFileSync(lockPath, 'utf-8'))).locales : {};
+    } catch {
+      state = {};
+    }
+  }
+  const sorted = sortKeys(manifest);
+  const cleanLocales = {};
+  for (const code of Object.keys(state || {}).sort()) {
+    const entry = state[code];
+    if (!entry || typeof entry !== 'object') continue;
+    const out = {};
+    for (const part of ['written', 'pending', 'refused', 'forms', 'gaps', 'by']) {
+      if (entry[part] && typeof entry[part] === 'object' && Object.keys(entry[part]).length > 0) {
+        out[part] = sortKeys(entry[part]);
+      }
+    }
+    if (Object.keys(out).length > 0) cleanLocales[code] = out;
   }
-  fs.writeFileSync(lockPath, JSON.stringify(sorted, null, 2) + '\n', 'utf-8');
+  const body = Object.keys(cleanLocales).length > 0
+    ? { version: LOCK_VERSION, source: sorted, locales: cleanLocales }
+    : sorted;
+  fs.writeFileSync(lockPath, JSON.stringify(body, null, 2) + '\n', 'utf-8');
+}
+
+/** A copy of an object with its own keys in sorted order. */
+function sortKeys(obj) {
+  const sorted = {};
+  for (const key of Object.keys(obj || {}).sort()) sorted[key] = obj[key];
+  return sorted;
 }
 
 export {
@@ -154,6 +277,8 @@ export {
   buildHashManifest,
   detectChangedKeys,
   readManifest,
+  readLock,
   writeManifest,
   LOCK_FILENAME,
+  LOCK_VERSION,
 };