locale-ai 0.6.2 → 0.6.4

package/README.md

@@ -15,7 +15,7 @@ npx locale-ai translate --from en --to fr,es,de
 ```
 
 ```
-locale-ai 0.2.0
+locale-ai 0.6.3
 Found 3 en files in locales/en/
 Models to download (one time, then cached for every project):
   en-fr         345 MB  khabouss/opus-mt-tc-big-en-fr-onnx
@@ -35,7 +35,7 @@ Download 577 MB? (Y/n)
 - **Incremental**: only missing keys are translated, existing translations are kept, re-runs are no-ops. `--overwrite` re-translates everything.
 - **Structure**: key order, numbers, booleans, arrays, indentation and trailing newline are preserved.
 
-**Format notes**: for `.po`, `msgid` is the stable key (never changed) and `msgstr` is the translated value, as gettext expects — the English `.po` file's `msgstr` must hold the source text (most generators already fill it; an empty `msgstr` is treated as empty, not inherited from `msgid`), and `msgid_plural`/`msgstr[n]` plural entries pass through untranslated (translate those by hand, or use ICU plurals in `.arb`/JSON/YAML instead). For `.arb`, `@key` metadata and `@@locale` are never translated; `@@locale` is set to the target locale on output.
+**Format notes**: for `.po`, `msgid` is the stable key (never changed) and `msgstr` is the translated value, as gettext expects — the English `.po` file's `msgstr` must hold the source text (most generators already fill it; an empty `msgstr` is treated as empty, not inherited from `msgid`). `msgid_plural`/`msgstr[n]` plural entries are translated too (the singular and plural source forms), then expanded to however many `msgstr[n]` the target language's plural rules need (6 for Arabic, 1 for Japanese, ...) — not full grammatical inflection for in-between categories (`few`/`many`/...), which get the plural-sourced translation verbatim, the same simplification `addPluralForms` makes for i18next. `Plural-Forms` in the header is computed for the target language, not copied from the source; an existing target file's header is otherwise left as you last edited it (a hand-fixed `Plural-Forms`, `Last-Translator`, ...) instead of being regenerated on every rerun. For `.arb`, `@key` metadata and `@@locale` are never translated; `@@locale` is set to the target locale on output.
 
 ## Why locale-ai?
 
@@ -50,6 +50,7 @@ Download 577 MB? (Y/n)
 
 ```bash
 locale-ai translate --to fr,pt-BR [--from en] [--input dir] [--dry-run] [--overwrite] [--fast] [--report file] [-y]
+locale-ai check [--from en] [--input dir]   # CI: fails if a translated locale has missing keys or placeholder mismatches
 locale-ai models list [--from en]     # supported language pairs
 locale-ai models installed
 locale-ai models install en-de        # pre-download (e.g. in CI)
@@ -102,24 +103,24 @@ then declare it in `locale-ai.config.json`:
 - `prefix` is required for multi-target models (`convert` lists the model's `>>xx<<` tokens).
 - Project models take priority over built-ins for their language pairs and can be used for pivoting (e.g. `ja → en → tr`).
 
-**Recommended for quality**: the `opus-mt-tc-big-en-*` models (es, it, pt, ar, tr, and `zle` for ru/uk). They are ~3x larger (270–370 MB int8) and ~1.5x slower, and clearly better. `en-fr` already uses one of these as its built-in model (see [Languages](#languages)), hosted at [khabouss/opus-mt-tc-big-en-fr-onnx](https://huggingface.co/khabouss/opus-mt-tc-big-en-fr-onnx) — no conversion needed for it.
+**Already built-in, no conversion needed**: `fr`, `es`, `it`, `pt`, `ar` and `tr` all use the larger, clearly-better `opus-mt-tc-big-en-*` checkpoints as their built-in model (~3x larger, 270–370 MB int8, ~1.5x slower than the plain OPUS-MT default); `ru`/`uk` use the tc-big `zle` multi-target checkpoint, and `pl` uses Helsinki-NLP's multi-target Slavic model (no tc-big `en-pl` checkpoint exists). The section above is for adding a language or model that *isn't* already built in.
 
-| Target | Built-in model, chrF / BLEU | tc-big model, chrF / BLEU |
+| Target | Previous (plain OPUS-MT), chrF / BLEU | Built-in today (tc-big / better), chrF / BLEU |
 |---|---|---|
+| fr | 68.9 / 53.7 | **72.5 / 55.9** |
 | es | 72.9 / 56.9 | **73.6 / 57.4** |
 | it | 73.8 / 54.9 | **75.3 / 58.2** |
 | pt | 68.3 / 44.4 | **70.6 / 47.7** (`>>por<<`, or `>>pob<<` for pt-BR) |
 | ru | 65.7 / 46.0 | **68.2 / 48.1** (`>>rus<<`) |
 | ar | 47.8 / 16.6 | **49.7 / 19.9** (`>>ara<<`, with `--fast`) |
-| tr | — | **67.4 / 42.1** |
+| tr | — | **67.4 / 42.1** (not supported before) |
+| pl | — | **62.6 / 40.3** (`>>pol<<`, not supported before) |
 
 300 Tatoeba test sentences per language, int8, beam 4 unless noted; reproduce with `bench/` (see `bench/README.md`). `opus-mt-tc-big-en-ko` is broken upstream (garbage output even in PyTorch) and is not recommended.
 
-Also new: **pl** (chrF 62.6 / BLEU 40.3, `>>pol<<`), hosted at [khabouss/opus-mt-en-sla-onnx](https://huggingface.co/khabouss/opus-mt-en-sla-onnx) — no tc-big `en-pl` checkpoint exists, so this uses Helsinki-NLP's multi-target Slavic model instead.
-
 ## Languages
 
-From English: af, ar, ca, cs, da, de, es, fi, fr, gl, hi, hu, id, it, nl, oc, pl, pt (pt-BR, pt-PT), ro, ru, sv, uk, vi, xh, zh (zh-CN, zh-TW). Other source languages are supported directly or through English (`locale-ai models list --from fr`).
+From English: af, ar, ca, cs, da, de, es, fi, fr, gl, hi, hu, id, it, nl, oc, pl, pt (pt-BR, pt-PT), ro, ru, sv, tr, uk, vi, xh, zh (zh-CN, zh-TW). Other source languages are supported directly or through English (`locale-ai models list --from fr`).
 
 Measured on a sample app (see `test/fixtures`):
 
@@ -129,7 +130,7 @@ Measured on a sample app (see `test/fixtures`):
 | Usable — review before shipping | it, ar, ru, pl, zh-CN, zh-TW |
 | Untested | the other pairs in `locale-ai models list` |
 
-`en-fr` is already on the tc-big model (chrF 72.5 / BLEU 55.9) as a built-in, no config needed. With the other tc-big models above, it, ar and ru move up a tier, and tr and pl become available. Not available yet: ja, ko and others; he works with a converted `opus-mt-en-he` (weaker). Moroccan Arabic (Darija): the tc-big en-ar model has a `>>ary<<` token, but its output is close to Modern Standard Arabic — not supported.
+`fr`, `es`, `it`, `pt`, `ar`, `ru`/`uk`, `tr` and `pl` all ship on the tc-big (or better) models above as built-ins already — no config needed. Not available yet: ja, ko and others; he works with a converted `opus-mt-en-he` (weaker). Moroccan Arabic (Darija): the tc-big en-ar model has a `>>ary<<` token, but its output is close to Modern Standard Arabic — not supported.
 
 ## How it works
 

package/dist/cli.js

@@ -9,14 +9,19 @@ import { CATALOG, customEntries, findById, reachableTargets, resolveRoute, } fro
 import { translateStrings } from "./engine.js";
 import { CONFIG_FILE, glossaryLookup, loadConfig, protectRegex } from "./glossary.js";
 import { intlCode, parseLocale } from "./lang.js";
-import { addPluralForms, buildTarget, detectLayout, pendingStrings, readLocaleDoc, sourceFiles, targetFile, } from "./locales.js";
+import { addPluralForms, buildTarget, detectLayout, existingTargets, flattenStrings, pendingStrings, readLocaleDoc, sourceFiles, targetFile, } from "./locales.js";
 import { cacheRoot, install, isInstalled, loadTranslator, localModelProblem, planInstall, readManifest, uninstall, } from "./models.js";
+import { mask } from "./placeholders.js";
 /** Read from package.json so `npm version` is the single source of truth. */
 const VERSION = JSON.parse(fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
 const HELP = `locale-ai ${VERSION} — translate i18n locale files locally, on CPU, for free.
 
 Usage:
   locale-ai translate --to <locales> [options]
+  locale-ai check [--from <locale>]
+                        Validate that already-translated locales have the same keys and
+                        placeholders as the source, without translating. Exits non-zero
+                        on a mismatch (CI-friendly).
   locale-ai models list [--from <locale>]
   locale-ai models installed
   locale-ai models install <from-to | model-id> [--yes]
@@ -49,16 +54,52 @@ const endStatus = () => {
 };
 const mb = (bytes) => `${Math.round(bytes / 1e6)} MB`;
 const rel = (p) => path.relative(process.cwd(), p) || ".";
+/**
+ * `Number("abc")` is NaN, and NaN silently poisons everything downstream (an
+ * all-garbage translation batch, or a raw ONNX crash deep in the model) instead of
+ * a clear error at the CLI boundary where the bad flag value actually came from.
+ */
+function positiveInt(raw, flag, fallback) {
+    if (raw === undefined) {
+        if (fallback === undefined)
+            throw new Error(`Missing --${flag}.`);
+        return fallback;
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error(`Invalid --${flag} "${raw}": expected a positive integer.`);
+    return n;
+}
 function bar(done, total, width = 24) {
     const ratio = total ? Math.min(1, done / total) : 1;
     const filled = Math.round(ratio * width);
     return `[${"█".repeat(filled)}${"░".repeat(width - filled)}] ${Math.round(ratio * 100)}%`;
 }
+/**
+ * A long download or translation batch can run for a minute or more. The `\r`-redrawn
+ * bar only ever reaches a real terminal, so a non-TTY run (CI logs, piped output) would
+ * otherwise print nothing at all between the start and the final result, indistinguishable
+ * from a hang. This prints one plain line per 10% there instead.
+ */
+function makeProgress(render) {
+    let lastPct = -1;
+    return (done, total) => {
+        if (isTTY) {
+            status(render(done, total));
+            return;
+        }
+        const pct = total ? Math.floor((done / total) * 100) : 100;
+        if (pct >= lastPct + 10 || (done >= total && lastPct < 100)) {
+            lastPct = done >= total ? 100 : pct;
+            log(render(done, total));
+        }
+    };
+}
 async function confirm(question, yes) {
     if (yes)
         return true;
     if (!process.stdin.isTTY) {
-        throw new Error(`${question.trim()} Re-run with --yes to allow downloads in non-interactive mode.`);
+        throw new Error(`Cannot ask "${question.trim()}" in a non-interactive shell. Re-run with --yes to allow downloads.`);
     }
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     const answer = (await rl.question(`${question} (Y/n) `)).trim().toLowerCase();
@@ -86,7 +127,7 @@ async function ensureInstalled(models, yes) {
     if (!(await confirm(`Download ${mb(total)}?`, yes)))
         throw new Error("Download declined.");
     for (const p of plans) {
-        await install(p, (d, t) => status(`Downloading ${p.model.id} ${bar(d, t)} ${mb(d)}/${mb(t)}`));
+        await install(p, makeProgress((d, t) => `Downloading ${p.model.id} ${bar(d, t)} ${mb(d)}/${mb(t)}`));
         endStatus();
         log(`✓ Installed ${p.model.id}`);
     }
@@ -105,10 +146,6 @@ async function cmdTranslate(argv) {
             beams: { type: "string" },
             report: { type: "string" },
             config: { type: "string" },
-            out: { type: "string" },
-            source: { type: "string" },
-            target: { type: "string" },
-            python: { type: "string" },
             yes: { type: "boolean", short: "y", default: false },
         },
     });
@@ -116,13 +153,13 @@ async function cmdTranslate(argv) {
         throw new Error("Missing --to. Example: locale-ai translate --from en --to fr,es");
     const from = parseLocale(values.from);
     const targets = values.to.split(",").map((t) => t.trim()).filter(Boolean).map(parseLocale);
-    const batchSize = Math.max(1, Number(values["batch-size"]));
-    const beams = Math.max(1, Number(values.beams ?? (values.fast ? 1 : 4)));
+    const batchSize = positiveInt(values["batch-size"], "batch-size");
+    const beams = positiveInt(values.beams, "beams", values.fast ? 1 : 4);
     const config = loadConfig(process.cwd(), values.config);
     const catalog = catalogFor(config);
     const protect = protectRegex(config);
     const layout = detectLayout(process.cwd(), from.tag, values.input);
-    const sources = sourceFiles(layout, from.tag).map((f) => ({ file: f, doc: readLocaleDoc(f) }));
+    const sources = sourceFiles(layout, from.tag).map((f) => ({ file: f, doc: readLocaleDoc(f, from.tag) }));
     log(`locale-ai ${VERSION}`);
     log(`Found ${sources.length} ${from.tag} file${sources.length === 1 ? "" : "s"} in ${rel(layout.root)}/` +
         (layout.kind === "dir" ? `${from.tag}/` : ""));
@@ -139,7 +176,7 @@ async function cmdTranslate(argv) {
         }
         const files = sources.map(({ file, doc }) => {
             const target = targetFile(layout, from.tag, locale.tag, file);
-            const existing = fs.existsSync(target) ? readLocaleDoc(target).data : undefined;
+            const existing = fs.existsSync(target) ? readLocaleDoc(target, locale.tag).data : undefined;
             return { source: file, target, doc, existing, pending: pendingStrings(doc.data, existing, values.overwrite) };
         });
         const unique = new Set(files.flatMap((f) => f.pending)).size;
@@ -182,7 +219,7 @@ async function cmdTranslate(argv) {
                 batchSize,
                 protect,
                 lookup: glossaryLookup(from, job.locale, config),
-                onProgress: (d, t) => status(`${job.locale.tag}: translating ${bar(d, t)} ${d}/${t}`),
+                onProgress: makeProgress((d, t) => `${job.locale.tag}: translating ${bar(d, t)} ${d}/${t}`),
             });
             endStatus();
             translations = result.translations;
@@ -201,8 +238,8 @@ async function cmdTranslate(argv) {
             const built = buildTarget(f.doc.data, f.existing, (s) => translations.get(s) ?? s, values.overwrite);
             const { doc, added } = addPluralForms(built, intlCode(job.locale));
             pluralsAdded += added;
-            const text = f.doc.serialize(doc, job.locale.tag);
             const before = fs.existsSync(f.target) ? fs.readFileSync(f.target, "utf8") : undefined;
+            const text = f.doc.serialize(doc, job.locale.tag, before);
             if (text !== before) {
                 fs.mkdirSync(path.dirname(f.target), { recursive: true });
                 fs.writeFileSync(f.target, text);
@@ -338,11 +375,70 @@ async function cmdModels(argv) {
             return sub ? 1 : 0;
     }
 }
+/**
+ * Validates already-translated locales against the source without translating:
+ * same key structure, and the same placeholders in each matching string. Meant for
+ * CI, so a mismatch (a key a translator dropped, a {name} a translation lost) fails
+ * the build instead of shipping silently.
+ */
+async function cmdCheck(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            from: { type: "string", default: "en" },
+            input: { type: "string" },
+        },
+    });
+    const from = parseLocale(values.from);
+    const layout = detectLayout(process.cwd(), from.tag, values.input);
+    const sources = sourceFiles(layout, from.tag).map((f) => ({ file: f, doc: readLocaleDoc(f, from.tag) }));
+    const targets = existingTargets(layout, from.tag);
+    if (!targets.length) {
+        log(`No translated locales found next to ${from.tag}.`);
+        return 0;
+    }
+    let problems = 0;
+    for (const to of targets) {
+        let missing = 0;
+        let mismatched = 0;
+        for (const { file, doc } of sources) {
+            const target = targetFile(layout, from.tag, to, file);
+            if (!fs.existsSync(target)) {
+                missing += flattenStrings(doc.data).length;
+                log(`✗ ${to}: ${rel(target)} is missing entirely`);
+                continue;
+            }
+            const srcFlat = flattenStrings(doc.data);
+            const tgtByPath = new Map(flattenStrings(readLocaleDoc(target, to).data).map((e) => [e.path, e.value]));
+            for (const { path: p, value: srcVal } of srcFlat) {
+                const tgtVal = tgtByPath.get(p);
+                if (tgtVal === undefined) {
+                    missing++;
+                    log(`✗ ${to}: ${rel(target)} missing key "${p}"`);
+                    continue;
+                }
+                const srcTokens = mask(srcVal, "natural").tokens.toSorted();
+                const tgtTokens = mask(tgtVal, "natural").tokens.toSorted();
+                if (srcTokens.join("\u0001") !== tgtTokens.join("\u0001")) {
+                    mismatched++;
+                    log(`✗ ${to}: ${rel(target)} "${p}" placeholders differ: source [${srcTokens.join(", ")}], target [${tgtTokens.join(", ")}]`);
+                }
+            }
+        }
+        if (missing || mismatched)
+            problems++;
+        else
+            log(`✓ ${to}`);
+    }
+    return problems ? 1 : 0;
+}
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     switch (cmd) {
         case "translate":
             return cmdTranslate(rest);
+        case "check":
+            return cmdCheck(rest);
         case "models":
             return cmdModels(rest);
         case "-v":

package/dist/engine.js

@@ -137,21 +137,34 @@ async function attempt(units, style, hops, opts, progress, issues) {
         }
         let ok = true;
         const found = [];
-        const joined = pieces
-            .map((p) => {
+        const parts = await Promise.all(pieces.map(async (p) => {
             // No spaces between sentences in Chinese, Japanese, Thai...
             if (!p.translate)
                 return NO_SPACES.test(opts.targetLang) ? p.value.replace(/^[ \t]+$/, "") : p.value;
-            const out = results.get(prepare(p.value)) ?? "";
-            if (isDegenerate(p.value, out))
+            let out = results.get(prepare(p.value)) ?? "";
+            const suspicionKind = (o) => o.length > 3 * p.value.length + 20 ? "suspicious-length" : /(\b\p{L}+\b)(?:\W+\1\b){3,}/u.test(o) ? "repetition" : undefined;
+            let degenerate = isDegenerate(p.value, out);
+            let kind = degenerate ? undefined : suspicionKind(out);
+            // Quantizing a batched tensor computes scale factors from the whole batch, so one
+            // row's output can depend on what else shared its batch. Retrying the same input
+            // alone (batch of 1) often clears a hallucination that batch composition caused.
+            if (degenerate || kind !== undefined) {
+                const retry = await runModels(new Set([prepare(p.value)]), hops, opts, progress);
+                const retryOut = retry.get(prepare(p.value)) ?? out;
+                const retryDegenerate = isDegenerate(p.value, retryOut);
+                if (!retryDegenerate && suspicionKind(retryOut) === undefined) {
+                    out = retryOut;
+                    degenerate = false;
+                    kind = undefined;
+                }
+            }
+            if (degenerate)
                 ok = false;
-            else if (out.length > 3 * p.value.length + 20)
-                found.push({ source: unit.owner, kind: "suspicious-length", output: out });
-            else if (/(\b\p{L}+\b)(?:\W+\1\b){3,}/u.test(out))
-                found.push({ source: unit.owner, kind: "repetition", output: out });
+            else if (kind)
+                found.push({ source: unit.owner, kind, output: out });
             return postprocess(p.value, out, opts.targetLang);
-        })
-            .join("");
+        }));
+        const joined = parts.join("");
         const restored = ok ? unmask(joined, masked) : undefined;
         if (restored === undefined)
             failed.push(unit);

package/dist/locales.js

@@ -82,6 +82,23 @@ export function targetFile(layout, from, to, src) {
         return path.join(layout.root, `${to}${layout.ext}`);
     return path.join(layout.root, to, path.relative(path.join(layout.root, from), src));
 }
+/** Locale tags already translated alongside `from` in this layout (for `locale-ai check`). */
+export function existingTargets(layout, from) {
+    if (layout.kind === "file") {
+        const ext = layout.ext;
+        return fs
+            .readdirSync(layout.root)
+            .filter((f) => f.endsWith(ext) && f.slice(0, -ext.length) !== from)
+            .map((f) => f.slice(0, -ext.length))
+            .sort();
+    }
+    return fs
+        .readdirSync(layout.root, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules" && e.name !== from)
+        .map((e) => e.name)
+        .filter((name) => listLocaleFiles(path.join(layout.root, name)).length > 0)
+        .sort();
+}
 const finalNewline = (text) => text === "" || text.endsWith("\n");
 const withNewline = (text, keep) => text.replace(/\n*$/, keep ? "\n" : "");
 function readJsonDoc(file, text) {
@@ -96,17 +113,28 @@ function readJsonDoc(file, text) {
     const keepNewline = finalNewline(text);
     return { data, serialize: (d) => withNewline(JSON.stringify(d, null, indent), keepNewline) };
 }
-function readYamlDoc(file, text) {
-    let data;
+/**
+ * Rails and some other frameworks nest an entire YAML locale file under a single
+ * top-level key matching the locale tag itself (`en:\n  hello: Hi`), so the file is
+ * valid wherever it's loaded from. Detect that wrapper and unwrap it before handing
+ * `data` to the rest of the pipeline (which otherwise treats "en" as just another
+ * translatable key), then re-wrap under the target's own tag on serialize.
+ */
+function readYamlDoc(file, text, tag) {
+    let raw;
     try {
-        data = parseYaml(text) ?? {};
+        raw = parseYaml(text) ?? {};
     }
     catch (e) {
         throw new Error(`Invalid YAML in ${file}: ${e.message}`);
     }
     const indent = Number(/\n( +)\S/.exec(text)?.[1].length) || 2;
     const keepNewline = finalNewline(text);
-    return { data, serialize: (d) => withNewline(stringifyYaml(d, { indent }), keepNewline) };
+    const keys = isObj(raw) ? Object.keys(raw) : [];
+    const wrapped = keys.length === 1 && keys[0] === tag;
+    const data = wrapped ? raw[tag] : raw;
+    const serialize = (d, targetTag) => withNewline(stringifyYaml(wrapped ? { [targetTag]: d } : d, { indent }), keepNewline);
+    return { data, serialize };
 }
 /** Apple .strings: `"key" = "value";`, optionally preceded by a `/* ... *\/` comment. */
 function unescapeC(s) {
@@ -116,7 +144,8 @@ function escapeC(s) {
     return s.replace(/[\\"\n\t\r]/g, (c) => ({ "\\": "\\\\", '"': '\\"', "\n": "\\n", "\t": "\\t", "\r": "\\r" })[c]);
 }
 function readStringsDoc(file, text) {
-    const PAIR = /(?:(\/\*[\s\S]*?\*\/)[ \t]*\r?\n+)?[ \t]*"((?:\\.|[^"\\])*)"\s*=\s*"((?:\\.|[^"\\])*)"\s*;/g;
+    // A key's preceding comment is either a /* ... */ block, or one or more consecutive // lines.
+    const PAIR = /(?:((?:\/\*[\s\S]*?\*\/)|(?:\/\/[^\r\n]*(?:\r?\n[ \t]*\/\/[^\r\n]*)*))[ \t]*\r?\n+)?[ \t]*"((?:\\.|[^"\\])*)"\s*=\s*"((?:\\.|[^"\\])*)"\s*;/g;
     const data = newObj();
     const entries = [];
     for (const m of text.matchAll(PAIR)) {
@@ -182,6 +211,58 @@ function readArbDoc(file, text) {
     return { data, serialize };
 }
 const poKey = (e) => (e.msgctxt ?? "") + "\u0004" + e.msgid;
+/**
+ * gettext's well-established Plural-Forms formulas, keyed by language. Copying the
+ * source header's line verbatim (as a naive patch does) is wrong whenever the target
+ * needs a different count — Arabic needs 6 categories, an English source's line says
+ * 2, and anything consuming the .po indexes msgstr[] short or drops forms silently.
+ */
+const PLURAL_FORMS = {
+    ja: "nplurals=1; plural=0;",
+    zh: "nplurals=1; plural=0;",
+    ko: "nplurals=1; plural=0;",
+    th: "nplurals=1; plural=0;",
+    vi: "nplurals=1; plural=0;",
+    id: "nplurals=1; plural=0;",
+    ms: "nplurals=1; plural=0;",
+    fr: "nplurals=2; plural=(n > 1);",
+    pt: "nplurals=2; plural=(n != 1);",
+    cs: "nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;",
+    sk: "nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;",
+    pl: "nplurals=3; plural=(n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<12 || n%100>14) ? 1 : 2);",
+    ru: "nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<12 || n%100>14) ? 1 : 2);",
+    uk: "nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<12 || n%100>14) ? 1 : 2);",
+    ro: "nplurals=3; plural=(n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2);",
+    ar: "nplurals=6; plural=(n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 : n%100>=11 && n%100<=99 ? 4 : 5);",
+};
+/**
+ * Falls back to CLDR's plural category count (via Intl.PluralRules) for a language
+ * not in the table above: not necessarily linguistically exact (it buckets purely by
+ * small integer value), but it keeps nplurals correct, which is the part that breaks
+ * gettext consumers when wrong.
+ */
+function pluralFormsHeader(lang) {
+    const known = PLURAL_FORMS[lang];
+    if (known)
+        return known;
+    let n;
+    try {
+        n = new Intl.PluralRules(lang).resolvedOptions().pluralCategories.length;
+    }
+    catch {
+        n = 2;
+    }
+    if (n <= 1)
+        return "nplurals=1; plural=0;";
+    if (n === 2)
+        return "nplurals=2; plural=(n != 1);";
+    const branches = Array.from({ length: n - 1 }, (_, i) => `n==${i + 1} ? ${i} :`).join(" ");
+    return `nplurals=${n}; plural=(${branches} ${n - 1});`;
+}
+/** The `nplurals=N` count from pluralFormsHeader, for expanding msgstr[] to the right length. */
+function pluralCount(lang) {
+    return Number(/nplurals=(\d+)/.exec(pluralFormsHeader(lang))[1]);
+}
 function parsePo(text) {
     const entries = [];
     let leading = [];
@@ -258,29 +339,62 @@ function parsePo(text) {
     flushEntry();
     return { entries, leading };
 }
+/** Synthetic data keys for a plural entry's two translatable forms. */
+const pluralOneKey = (e) => poKey(e) + "\u0005one";
+const pluralOtherKey = (e) => poKey(e) + "\u0005other";
 function readPoDoc(file, text) {
     const { entries, leading } = parsePo(text);
     const data = newObj();
-    for (const e of entries)
-        if (!e.isHeader && e.msgidPlural === undefined)
+    for (const e of entries) {
+        if (e.isHeader)
+            continue;
+        if (e.msgidPlural === undefined)
             data[poKey(e)] = e.msgstr;
+        else {
+            // Like msgstr for a singular entry, msgstrPlural holds this FILE's own text: the
+            // English source form in the source .po, the translated forms in a target .po
+            // (msgid/msgid_plural are the stable keys, identical across every locale).
+            const forms = e.msgstrPlural ?? [];
+            data[pluralOneKey(e)] = forms[0] ?? "";
+            data[pluralOtherKey(e)] = forms[forms.length - 1] ?? forms[0] ?? "";
+        }
+    }
     const keepNewline = finalNewline(text);
-    const serialize = (d, targetTag) => {
+    const serialize = (d, targetTag, existingText) => {
         const obj = isObj(d) ? d : newObj();
         const seen = new Set();
         const blocks = leading.length ? [leading.join("\n")] : [];
+        // A previous run may have left a header a translator then hand-fixed (a corrected
+        // Plural-Forms, an added Last-Translator, ...). Keep it as-is rather than
+        // regenerating from the source every time; only a brand-new target file gets a
+        // freshly computed header.
+        const existingHeader = existingText && parsePo(existingText).entries.find((e) => e.isHeader);
         for (const e of entries) {
             const lines = [...e.comments];
             if (e.msgctxt !== undefined)
                 lines.push(`msgctxt "${escapeC(e.msgctxt)}"`);
             if (e.isHeader) {
                 lines.push(`msgid ""`);
-                const header = e.msgstr.replace(/^Language:.*$/m, `Language: ${targetTag}`);
+                const header = existingHeader
+                    ? existingHeader.msgstr
+                    : e.msgstr.replace(/^Language:.*$/m, `Language: ${targetTag}`).replace(/^Plural-Forms:.*$/m, `Plural-Forms: ${pluralFormsHeader(targetTag)}`);
                 lines.push(`msgstr "${escapeC(header)}"`);
             }
             else if (e.msgidPlural !== undefined) {
                 lines.push(`msgid "${escapeC(e.msgid)}"`, `msgid_plural "${escapeC(e.msgidPlural)}"`);
-                (e.msgstrPlural ?? []).forEach((s, i) => lines.push(`msgstr[${i}] "${escapeC(s)}"`));
+                const oneKey = pluralOneKey(e);
+                const otherKey = pluralOtherKey(e);
+                seen.add(oneKey);
+                seen.add(otherKey);
+                const one = typeof obj[oneKey] === "string" ? obj[oneKey] : e.msgid;
+                const other = typeof obj[otherKey] === "string" ? obj[otherKey] : e.msgidPlural;
+                const n = pluralCount(targetTag);
+                // Not full grammatical inflection (same simplification as addPluralForms for
+                // i18next): index 0 gets the singular-sourced form, every other index the
+                // plural-sourced one. A language with only one category (ja, zh, ...) gets
+                // just the plural form, since it has no separate singular count.
+                for (let i = 0; i < n; i++)
+                    lines.push(`msgstr[${i}] "${escapeC(n === 1 ? other : i === 0 ? one : other)}"`);
             }
             else {
                 const key = poKey(e);
@@ -304,11 +418,12 @@ function readPoDoc(file, text) {
     };
     return { data, serialize };
 }
-export function readLocaleDoc(file) {
+/** `tag` is the locale this file is for (the source tag, or an existing target's own tag). */
+export function readLocaleDoc(file, tag) {
     const text = fs.readFileSync(file, "utf8").replace(/^/, "");
     const ext = path.extname(file).toLowerCase();
     if (ext === ".yaml" || ext === ".yml")
-        return readYamlDoc(file, text);
+        return readYamlDoc(file, text, tag);
     if (ext === ".po")
         return readPoDoc(file, text);
     if (ext === ".arb")
@@ -322,6 +437,17 @@ const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const newObj = () => Object.create(null);
 /** A string needs translating when the target has no non-empty string at the same path. */
 const needsTranslation = (existing, overwrite) => overwrite || typeof existing !== "string" || existing === "";
+/** Flattens a locale tree into key-path -> string-value pairs (for `locale-ai check`). */
+export function flattenStrings(data, prefix = "", out = []) {
+    if (typeof data === "string")
+        out.push({ path: prefix || "(root)", value: data });
+    else if (Array.isArray(data))
+        data.forEach((v, i) => flattenStrings(v, `${prefix}[${i}]`, out));
+    else if (isObj(data))
+        for (const k of Object.keys(data))
+            flattenStrings(data[k], prefix ? `${prefix}.${k}` : k, out);
+    return out;
+}
 export function pendingStrings(source, existing, overwrite, out = []) {
     if (typeof source === "string") {
         if (needsTranslation(existing, overwrite))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locale-ai",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Translate your i18n locale files locally on CPU. Free, offline, no API keys.",
   "author": "Taha KHABOUSS",
   "repository": {