locale-ai 0.6.5 → 0.6.6

package/README.md

@@ -32,7 +32,7 @@ Download 577 MB? (Y/n)
 - **Placeholders are never translated or lost**: `{name}`, `{{count}}`, `%s`, `%1$s`, `%(name)s`, `%{name}`, `${name}`, `:attribute`, `$t(key)`, `@:key`, `<b>…</b>`, `<0>…</0>`, `&nbsp;`, URLs, e-mails.
 - **ICU MessageFormat**: `{count, plural, one {# file} other {# files}}`, `select`, nesting. Only the text is translated.
 - **i18next plurals**: adds the forms the target language needs (`_few`, `_many` for Arabic, Russian, Polish...), so the app doesn't fall back to the English string — each added form copies the `_other` translation verbatim rather than inflecting it, so review and adjust the wording of `_zero`/`_two`/`_few`/`_many` by hand for languages where those forms use a different noun/adjective form. The `_one` form is translated with its `{{count}}` temporarily replaced by a literal "1", since the model otherwise sometimes picks the target's plural noun form despite the English source being grammatically singular.
-- **Incremental**: only missing keys are translated, existing translations are kept, re-runs are no-ops. `--overwrite` re-translates everything.
+- **Incremental, and edit-aware**: only missing or changed keys are translated; untouched translations are kept, so re-runs are no-ops. A small `locale-ai.lock.json` (commit it, like a package lock) remembers a hash of each source string and of the output last written for it per target locale — so editing a source string gets it re-translated automatically (it isn't enough for the target to already hold *some* text), while editing a target string by hand is detected and reported for review instead of being silently overwritten on the next run. `--overwrite` bypasses the lock and 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`). `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.
@@ -41,7 +41,7 @@ Download 577 MB? (Y/n)
 
 - **No API keys, no cloud bill.** Google/DeepL/OpenAI-based translation tools work well but mean an account, a key, a per-character cost, and your strings leaving your machine. locale-ai runs the model on your own CPU.
 - **Built for i18n files, not plain text.** General MT tools translate strings; they don't know that `{count}`, `<0>bold</0>`, or `$t(common.footer.tagline)` must survive untouched. locale-ai is built around i18next/ICU conventions specifically, so placeholders, plurals, and nested references come out intact instead of mangled or dropped.
-- **Incremental by default.** Add one new key to `en.json` and only that key gets translated — existing translations in `fr.json`/`es.json`/etc. are left alone, so re-runs are cheap and safe to automate in CI.
+- **Incremental by default.** Add one new key to `en.json` and only that key gets translated; edit an existing one and the lockfile catches it and re-translates just that key — existing, unrelated translations are left alone, so re-runs are cheap and safe to automate in CI.
 - **Honest about quality.** The [Languages](#languages) section tells you which pairs are review-light vs. which need a human pass, instead of presenting every language as equally production-ready.
 
 **When *not* to use it**: if you need professional/legal-grade translation, or languages outside the [supported list](#languages), use a human translator or a larger cloud model instead — locale-ai is built for keeping UI strings in sync across languages during development, with a review pass before shipping.

package/dist/cli.js

@@ -9,6 +9,7 @@ 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 { editedPaths, isSourceStale, LOCK_FILENAME, loadLock, recordEntries, saveLock } from "./lock.js";
 import { addPluralForms, buildTarget, detectLayout, existingTargets, flattenStrings, keyPathProtect, pendingStrings, pluralOneStrings, readLocaleDoc, sourceFiles, targetFile, } from "./locales.js";
 import { cacheRoot, install, isInstalled, loadTranslator, localModelProblem, planInstall, readManifest, uninstall, } from "./models.js";
 import { mask } from "./placeholders.js";
@@ -54,6 +55,8 @@ const endStatus = () => {
 };
 const mb = (bytes) => `${Math.round(bytes / 1e6)} MB`;
 const rel = (p) => path.relative(process.cwd(), p) || ".";
+/** Portable lock-file key: forward slashes regardless of platform. */
+const fileKey = (p) => rel(p).split(path.sep).join("/");
 /**
  * `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
@@ -160,6 +163,8 @@ async function cmdTranslate(argv) {
     const protect = protectRegex(config);
     const isProtectedKey = keyPathProtect(config.doNotTranslateKeys);
     const layout = detectLayout(process.cwd(), from.tag, values.input);
+    const lockPath = path.resolve(process.cwd(), LOCK_FILENAME);
+    const lock = loadLock(lockPath);
     const sources = sourceFiles(layout, from.tag).map((f) => ({ file: f, doc: readLocaleDoc(f, from.tag) }));
     const singularHints = new Set(sources.flatMap(({ doc }) => [...pluralOneStrings(doc.data)]));
     log(`locale-ai ${VERSION}`);
@@ -179,12 +184,13 @@ 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, locale.tag).data : undefined;
+            const isStale = (p, s) => isSourceStale(lock, fileKey(file), p, s);
             return {
                 source: file,
                 target,
                 doc,
                 existing,
-                pending: pendingStrings(doc.data, existing, values.overwrite, isProtectedKey),
+                pending: pendingStrings(doc.data, existing, values.overwrite, isProtectedKey, isStale),
             };
         });
         const unique = new Set(files.flatMap((f) => f.pending)).size;
@@ -244,7 +250,14 @@ async function cmdTranslate(argv) {
         let written = 0;
         let pluralsAdded = 0;
         for (const f of job.files) {
-            const built = buildTarget(f.doc.data, f.existing, (s) => translations.get(s) ?? s, values.overwrite, isProtectedKey);
+            const lockKey = fileKey(f.source);
+            const isStale = (p, s) => isSourceStale(lock, lockKey, p, s);
+            if (f.existing !== undefined) {
+                for (const editedPath of editedPaths(lock, lockKey, job.locale.tag, flattenStrings(f.existing))) {
+                    allIssues.push({ source: editedPath, kind: "edited", locale: job.locale.tag });
+                }
+            }
+            const built = buildTarget(f.doc.data, f.existing, (s) => translations.get(s) ?? s, values.overwrite, isProtectedKey, isStale);
             const { doc, added } = addPluralForms(built, intlCode(job.locale));
             pluralsAdded += added;
             const before = fs.existsSync(f.target) ? fs.readFileSync(f.target, "utf8") : undefined;
@@ -254,6 +267,8 @@ async function cmdTranslate(argv) {
                 fs.writeFileSync(f.target, text);
                 written++;
             }
+            const outFlat = new Map(flattenStrings(doc).map((e) => [e.path, e.value]));
+            recordEntries(lock, lockKey, job.locale.tag, flattenStrings(f.doc.data).map(({ path: p, value }) => ({ path: p, source: value, written: outFlat.get(p) ?? "" })));
         }
         const secs = ((Date.now() - started) / 1000).toFixed(1);
         const issues = allIssues.filter((i) => i.locale === job.locale.tag).length;
@@ -264,6 +279,8 @@ async function cmdTranslate(argv) {
     }
     for (const t of loaded.values())
         await t.dispose();
+    if (jobs.length)
+        saveLock(lockPath, lock);
     if (allIssues.length) {
         log();
         log(`${allIssues.length} string${allIssues.length === 1 ? "" : "s"} worth a quick review:`);

package/dist/locales.js

@@ -461,11 +461,11 @@ export function keyPathProtect(doNotTranslateKeys) {
         return undefined;
     return (path) => keys.some((k) => path === k || path.startsWith(`${k}.`) || path.startsWith(`${k}[`));
 }
-export function pendingStrings(source, existing, overwrite, isProtected) {
+export function pendingStrings(source, existing, overwrite, isProtected, isStale) {
     const out = [];
     const visit = (s, e, path) => {
         if (typeof s === "string") {
-            if (!isProtected?.(path) && needsTranslation(e, overwrite))
+            if (!isProtected?.(path) && (needsTranslation(e, overwrite) || !!isStale?.(path, s)))
                 out.push(s);
         }
         else if (Array.isArray(s)) {
@@ -481,16 +481,19 @@ export function pendingStrings(source, existing, overwrite, isProtected) {
 }
 /**
  * Builds the target document: source structure and key order, existing
- * translations kept (unless overwrite), new strings from `translate`, and keys
- * that only exist in the target preserved at the end. A string at a protected
- * path (see keyPathProtect) is always copied from the source verbatim.
+ * translations kept (unless overwrite or stale), new strings from `translate`,
+ * and keys that only exist in the target preserved at the end. A string at a
+ * protected path (see keyPathProtect) is always copied from the source
+ * verbatim. `isStale` (see the lock module) forces re-translation of a
+ * non-empty target when its source string has changed since it was last
+ * translated.
  */
-export function buildTarget(source, existing, translate, overwrite, isProtected) {
+export function buildTarget(source, existing, translate, overwrite, isProtected, isStale) {
     const visit = (s, e, path) => {
         if (typeof s === "string") {
             if (isProtected?.(path))
                 return s;
-            return needsTranslation(e, overwrite) ? translate(s) : e;
+            return needsTranslation(e, overwrite) || isStale?.(path, s) ? translate(s) : e;
         }
         if (Array.isArray(s))
             return s.map((v, i) => visit(v, Array.isArray(e) ? e[i] : undefined, `${path}[${i}]`));

package/dist/lock.js

@@ -0,0 +1,56 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+export const LOCK_FILENAME = "locale-ai.lock.json";
+export function hashOf(s) {
+    return crypto.createHash("sha256").update(s, "utf8").digest("hex").slice(0, 16);
+}
+export function loadLock(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (parsed && typeof parsed === "object" && parsed.files)
+            return { version: 1, files: parsed.files };
+    }
+    catch {
+        // Missing or invalid: start fresh rather than fail the run.
+    }
+    return { version: 1, files: {} };
+}
+export function saveLock(file, lock) {
+    fs.writeFileSync(file, `${JSON.stringify(lock, null, 2)}\n`);
+}
+/**
+ * True when `path`'s source string in `fileKey` has changed since it was last
+ * translated — meaning the existing target text is stale and needs redoing
+ * even though it's non-empty. False for a path the lock has never seen (new
+ * adoption, or a brand-new key, both already handled by the empty-target check).
+ */
+export function isSourceStale(lock, fileKey, path, source) {
+    const entry = lock.files[fileKey]?.[path];
+    return entry !== undefined && entry.source !== hashOf(source);
+}
+/**
+ * Key paths whose existing target text no longer matches the output this tool
+ * last wrote there for `targetTag` — i.e. a translator edited it since. Only
+ * reported; the edit is never overwritten.
+ */
+export function editedPaths(lock, fileKey, targetTag, entries) {
+    const file = lock.files[fileKey];
+    if (!file)
+        return [];
+    const out = [];
+    for (const { path, value } of entries) {
+        const mt = file[path]?.mt[targetTag];
+        if (mt !== undefined && mt !== hashOf(value))
+            out.push(path);
+    }
+    return out;
+}
+/** Records, for every path translated this run, the current source hash and the hash of what ended up on disk. */
+export function recordEntries(lock, fileKey, targetTag, entries) {
+    const file = (lock.files[fileKey] ??= {});
+    for (const { path, source, written } of entries) {
+        const entry = (file[path] ??= { source: hashOf(source), mt: {} });
+        entry.source = hashOf(source);
+        entry.mt[targetTag] = hashOf(written);
+    }
+}

package/package.json

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