locale-ai 0.6.17 → 0.6.18

package/README.md

@@ -28,7 +28,7 @@ Download 577 MB? (Y/n)
 
 ## What it handles
 
-- **Layouts**: `locales/en/*.json` (nested folders too) → `locales/fr/...`, or `messages/en.json` → `messages/fr.json`. `.json`, `.yaml`, `.yml`, `.po`/`.pot` (gettext), `.arb` (Flutter) and `.strings` (Apple) are all supported, mixed freely in the same project. Common folders (`locales`, `src/locales`, `public/locales`, `src/i18n`, `messages`, `lang`, `config/locales` (Rails), ...) are found automatically, or pass `--input`. Framework-specific naming is also recognized: `flutter gen-l10n`'s `app_en.arb`/`app_fr.arb` filename prefix, and Apple's `en.lproj`/`fr.lproj` directory-suffix convention (`--input en.lproj` or just the project root both work), on both the source and the generated target side.
+- **Layouts**: `locales/en/*.json` (nested folders too) → `locales/fr/...`, or `messages/en.json` → `messages/fr.json`. `.json`, `.yaml`, `.yml`, `.po`/`.pot` (gettext), `.arb` (Flutter), `.strings` (Apple) and `.properties` (Java) are all supported, mixed freely in the same project. Common folders (`locales`, `src/locales`, `public/locales`, `src/i18n`, `messages`, `lang`, `config/locales` (Rails), ...) are found automatically, or pass `--input`. Framework-specific naming is also recognized: `flutter gen-l10n`'s `app_en.arb`/`app_fr.arb` filename prefix, Apple's `en.lproj`/`fr.lproj` directory-suffix convention (`--input en.lproj` or just the project root both work), and Java `ResourceBundle`'s `messages_en.properties`/`messages_fr.properties` filename prefix (region-qualified as `messages_pt_BR.properties`, with an underscore — Java's own convention, not this project's usual BCP-47 hyphen), on both the source and the generated target side.
 - **Android**: `res/values/strings.xml` → `res/values-fr/strings.xml` (or `values-pt-rBR` for a region). `<string>`, `<string-array>` and `<plurals>` are all translated; `translatable="false"` strings and `<!-- ... -->` comments are kept as-is. Resource-qualifier scripts/variants (`values-b+sr+Latn`) aren't supported — only a plain language or language-region qualifier.
 - **Apple `.xcstrings`** (Xcode 15+'s String Catalog, replacing `.strings`): every locale lives inside this one file, so point `--input` straight at it (e.g. `--input Localizable.xcstrings`; it isn't auto-detected, since a project can have several). `shouldTranslate: false` entries, and Xcode's per-device variants (`variations.iphone`/`.ipad`) or multi-variable strings (`substitutions`), are left untouched rather than mistranslated — only a single cardinal plural (`variations.plural`) is supported. A key with no explicit source-language text falls back to the key itself, matching Xcode's own convention.
 - **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.
@@ -37,7 +37,7 @@ Download 577 MB? (Y/n)
 - **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 `.yaml`/`.yml`, `#` comments (a translator note, an inline `# ...` after a value) survive a translation run — the target file is edited in place rather than rebuilt from scratch, so an existing comment's own value is updated without disturbing the comment, and a brand-new key is appended with no comment of its own. A newly added plural-category key (see above) is likewise appended rather than inserted between existing ones, so its position in the file won't always match the canonical `zero`/`one`/`two`/`few`/`many`/`other` order. For `.po`/`.pot`, `msgid` is the stable key (never changed) and `msgstr` is the translated value, as gettext expects — the English source's `msgstr` holds the source text when it's filled in (most generators do), and falls back to `msgid` itself when it's empty, which is normal for a `.pot` template or a project that just keeps the English text in `msgid`. That fallback only ever applies to the source file: an empty `msgstr` in an *existing target* still means "not translated yet", never "same as 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, and any entry's own comments (a translator's note, a hand-added `#, fuzzy`), are otherwise left exactly as last edited instead of being regenerated from the source on every rerun. `--fuzzy` flags every entry a run actually (re)translated with gettext's standard `#, fuzzy` "needs review" marker, merging onto an existing `#,` line rather than adding a second one. A `.pot` source always writes a `.po` target, never a `.pot`. For `.arb`, `@key` metadata and `@@locale` are never translated; `@@locale` is set to the target locale on output. For `.strings`, a file saved as UTF-16 (Xcode's traditional default) is read like a UTF-8 one, an unquoted key (`title = "Settings";`, without quotes around `title`) is read the same as a quoted one, and `\U00e9`-style escapes are decoded — output is always written as UTF-8 with quoted keys, regardless of how the source was saved. For Android `strings.xml`, `translatable="false"` strings and each element's own `<!-- ... -->` comment are kept on first write, but — unlike YAML/`.po`/`.strings` — a rerun regenerates the file from scratch rather than editing an existing target in place, so a hand-edited comment in an already-translated file won't survive a rerun. For `.xcstrings`, every target locale is written into the same one catalog file (each locale's run re-reads it first, so several locales share it safely in one invocation); an entry's `state` (e.g. a translator's `needs_review` flag) is only touched when the value it's attached to actually changes, so hand review survives a rerun.
+**Format notes**: for `.yaml`/`.yml`, `#` comments (a translator note, an inline `# ...` after a value) survive a translation run — the target file is edited in place rather than rebuilt from scratch, so an existing comment's own value is updated without disturbing the comment, and a brand-new key is appended with no comment of its own. A newly added plural-category key (see above) is likewise appended rather than inserted between existing ones, so its position in the file won't always match the canonical `zero`/`one`/`two`/`few`/`many`/`other` order. For `.po`/`.pot`, `msgid` is the stable key (never changed) and `msgstr` is the translated value, as gettext expects — the English source's `msgstr` holds the source text when it's filled in (most generators do), and falls back to `msgid` itself when it's empty, which is normal for a `.pot` template or a project that just keeps the English text in `msgid`. That fallback only ever applies to the source file: an empty `msgstr` in an *existing target* still means "not translated yet", never "same as 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, and any entry's own comments (a translator's note, a hand-added `#, fuzzy`), are otherwise left exactly as last edited instead of being regenerated from the source on every rerun. `--fuzzy` flags every entry a run actually (re)translated with gettext's standard `#, fuzzy` "needs review" marker, merging onto an existing `#,` line rather than adding a second one. A `.pot` source always writes a `.po` target, never a `.pot`. For `.arb`, `@key` metadata and `@@locale` are never translated; `@@locale` is set to the target locale on output. For `.strings`, a file saved as UTF-16 (Xcode's traditional default) is read like a UTF-8 one, an unquoted key (`title = "Settings";`, without quotes around `title`) is read the same as a quoted one, and `\U00e9`-style escapes are decoded — output is always written as UTF-8 with quoted keys, regardless of how the source was saved. For Android `strings.xml`, `translatable="false"` strings and each element's own `<!-- ... -->` comment are kept on first write, but — unlike YAML/`.po`/`.strings` — a rerun regenerates the file from scratch rather than editing an existing target in place, so a hand-edited comment in an already-translated file won't survive a rerun. For `.xcstrings`, every target locale is written into the same one catalog file (each locale's run re-reads it first, so several locales share it safely in one invocation); an entry's `state` (e.g. a translator's `needs_review` flag) is only touched when the value it's attached to actually changes, so hand review survives a rerun. For `.properties`, `#`/`!` comments and blank lines survive a rerun exactly like YAML's — the target file is edited in place rather than rebuilt from scratch; a `\`-continued multi-line value is read correctly but gets collapsed onto one line if it's ever actually rewritten (an untouched one keeps its original layout), and a line with no unescaped `=`/`:` at all is left completely alone rather than guessed at. `.properties` has no plural convention of its own, so ICU `{count, plural, ...}` inside a value is handled the same generic way it is everywhere else.
 
 ## Why locale-ai?
 

package/dist/locales.js

@@ -2,7 +2,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { Document, isMap, isScalar, parseDocument } from "yaml";
 import { parseLocale } from "./lang.js";
-const EXTENSIONS = [".json", ".yaml", ".yml", ".po", ".pot", ".arb", ".strings"];
+const EXTENSIONS = [".json", ".yaml", ".yml", ".po", ".pot", ".arb", ".strings", ".properties"];
+/**
+ * Java's `ResourceBundle` convention names a region-qualified `.properties` file
+ * "fr_FR", not this project's BCP-47 "fr-FR" everywhere else — so the tag is
+ * underscore-joined only at the filename boundary, for this one extension.
+ */
+const propertiesTag = (ext, tag) => (ext === ".properties" ? tag.replace("-", "_") : tag);
+const tagFromPropertiesQualifier = (ext, qualifier) => (ext === ".properties" ? qualifier.replace("_", "-") : qualifier);
 const CANDIDATES = [
     "locales",
     "src/locales",
@@ -45,11 +52,12 @@ const isDir = (p) => fs.existsSync(p) && fs.statSync(p).isDirectory();
 const isFile = (p) => fs.existsSync(p) && fs.statSync(p).isFile();
 /** The source-locale file's extension, if `<root>/<from><ext>` exists for one of EXTENSIONS. */
 function fileExtAt(root, from) {
-    return EXTENSIONS.find((ext) => isFile(path.join(root, `${from}${ext}`)));
+    return EXTENSIONS.find((ext) => isFile(path.join(root, `${propertiesTag(ext, from)}${ext}`)));
 }
 /**
  * A prefixed source-locale file, if `<root>/<prefix>_<from><ext>` exists for one of
- * EXTENSIONS — the convention `flutter gen-l10n` uses by default ("app_en.arb").
+ * EXTENSIONS — the convention `flutter gen-l10n` uses by default ("app_en.arb"), and
+ * also how a Java `ResourceBundle` basename ("messages_en.properties") is found.
  */
 function prefixedFileAt(root, from) {
     if (!isDir(root))
@@ -58,7 +66,7 @@ function prefixedFileAt(root, from) {
         if (!isFile(path.join(root, entry)))
             continue;
         for (const ext of EXTENSIONS) {
-            const suffix = `_${from}${ext}`;
+            const suffix = `_${propertiesTag(ext, from)}${ext}`;
             if (entry.endsWith(suffix) && entry.length > suffix.length) {
                 return { ext, prefix: entry.slice(0, -suffix.length) };
             }
@@ -89,7 +97,7 @@ function layoutAt(root, from) {
     return undefined;
 }
 const dirNameFor = (layout, tag) => `${tag}${layout.dirSuffix ?? ""}`;
-const fileNameFor = (layout, tag, ext) => `${layout.prefix ? `${layout.prefix}_` : ""}${tag}${ext}`;
+const fileNameFor = (layout, tag, ext) => `${layout.prefix ? `${layout.prefix}_` : ""}${propertiesTag(ext, tag)}${ext}`;
 export function detectLayout(cwd, from, input) {
     if (input) {
         const abs = path.resolve(cwd, input);
@@ -117,12 +125,15 @@ export function detectLayout(cwd, from, input) {
             return { kind: "xcstrings", root: path.dirname(abs), file: abs };
         }
         const base = path.basename(abs);
-        const directExt = EXTENSIONS.find((ext) => base === `${from}${ext}`);
+        const directExt = EXTENSIONS.find((ext) => base === `${propertiesTag(ext, from)}${ext}`);
         if (directExt && isFile(abs))
             return { kind: "file", root: path.dirname(abs), ext: directExt };
-        const prefixedExt = EXTENSIONS.find((ext) => base.endsWith(`_${from}${ext}`) && base.length > `_${from}${ext}`.length);
+        const prefixedExt = EXTENSIONS.find((ext) => {
+            const suffix = `_${propertiesTag(ext, from)}${ext}`;
+            return base.endsWith(suffix) && base.length > suffix.length;
+        });
         if (prefixedExt && isFile(abs)) {
-            const suffix = `_${from}${prefixedExt}`;
+            const suffix = `_${propertiesTag(prefixedExt, from)}${prefixedExt}`;
             return { kind: "file", root: path.dirname(abs), ext: prefixedExt, prefix: base.slice(0, -suffix.length) };
         }
         const l = layoutAt(abs, from);
@@ -216,9 +227,9 @@ export function existingTargets(layout, from) {
         const prefix = layout.prefix ? `${layout.prefix}_` : "";
         return fs
             .readdirSync(layout.root)
-            .filter((f) => f.startsWith(prefix) && f.endsWith(ext) && f.slice(prefix.length, -ext.length) !== from)
-            .map((f) => f.slice(prefix.length, -ext.length))
-            .filter(looksLikeLocale)
+            .filter((f) => f.startsWith(prefix) && f.endsWith(ext))
+            .map((f) => tagFromPropertiesQualifier(ext, f.slice(prefix.length, -ext.length)))
+            .filter((tag) => tag !== from && looksLikeLocale(tag))
             .sort();
     }
     const suffix = layout.dirSuffix ?? "";
@@ -367,6 +378,109 @@ function readStringsDoc(file, text) {
     };
     return { data, serialize };
 }
+/** Java `.properties`: `\n`, `\t`, `\r`, `\f`, `\\` and `\uXXXX` escapes, plus an escaped separator/leading-space. */
+function unescapeProperties(s) {
+    return s.replace(/\\(u[0-9a-fA-F]{4}|.)/gs, (_m, esc) => {
+        if (esc[0] === "u" && esc.length === 5)
+            return String.fromCharCode(parseInt(esc.slice(1), 16));
+        return { n: "\n", t: "\t", r: "\r", f: "\f" }[esc] ?? esc;
+    });
+}
+function escapeProperties(s) {
+    let out = s.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(/\r/g, "\\r");
+    if (out[0] === " ")
+        out = `\\${out}`;
+    return out;
+}
+/** True when `s` ends in an odd run of backslashes — Java's line-continuation rule. */
+const endsWithContinuation = (s) => (/\\*$/.exec(s)[0].length % 2 === 1);
+/** Splits `key<ws>?[=:]<ws>?value` at the first unescaped `=`/`:`, skipping `\X` pairs. Undefined if there's none (a key-only or malformed line). */
+function splitPropertyLine(line) {
+    let i = 0;
+    while (i < line.length) {
+        const c = line[i];
+        if (c === "\\") {
+            i += 2;
+            continue;
+        }
+        if (c === "=" || c === ":") {
+            const key = unescapeProperties(line.slice(0, i).trimEnd());
+            let v = i + 1;
+            while (v < line.length && (line[v] === " " || line[v] === "\t"))
+                v++;
+            return { key, valueStart: v };
+        }
+        i++;
+    }
+    return undefined;
+}
+/** Parses `.properties` text into passthrough lines (comments, blank lines, unparsable lines) and key/value entries. */
+function parsePropertiesBlocks(text) {
+    const physical = text.split(/\r?\n/);
+    const blocks = [];
+    const data = newObj();
+    let i = 0;
+    while (i < physical.length) {
+        const line = physical[i];
+        const trimmedStart = line.replace(/^[ \t\f]+/, "");
+        if (trimmedStart === "" || trimmedStart[0] === "#" || trimmedStart[0] === "!") {
+            blocks.push({ text: line });
+            i++;
+            continue;
+        }
+        const split = splitPropertyLine(line);
+        if (!split) {
+            blocks.push({ text: line });
+            i++;
+            continue;
+        }
+        let valueRaw = line.slice(split.valueStart);
+        while (endsWithContinuation(valueRaw) && i + 1 < physical.length) {
+            valueRaw = valueRaw.slice(0, -1) + physical[++i].replace(/^[ \t\f]+/, "");
+        }
+        data[split.key] = unescapeProperties(valueRaw);
+        blocks.push({ key: split.key, prefix: line.slice(0, split.valueStart) });
+        i++;
+    }
+    return { blocks, data };
+}
+/**
+ * Java `ResourceBundle` `.properties`: a flat `key=value` (or `key: value`) list, one
+ * per line, `#`/`!` line comments, `\`-continued multi-line values, and `\uXXXX`/`\n`/
+ * `\t` escapes. There's no plural or array convention of its own — a value containing
+ * ICU `{count, plural, ...}` syntax is still handled generically by the ICU extractor
+ * elsewhere, same as any other format.
+ *
+ * Unlike Android/ARB/`.xcstrings` (which regenerate the whole file from the source's
+ * own structure every run), this edits an existing target file's lines in place, the
+ * same as YAML/`.po`: untouched entries, comments and blank lines keep their exact
+ * text and position, and a value that didn't change is never rewritten. A multi-line
+ * (`\`-continued) value is always collapsed to one line when it's rewritten, though —
+ * only an *unchanged* continued value keeps its original multi-line layout. A line
+ * with no unescaped `=`/`:` at all (so not a recognizable `key=value` pair) is passed
+ * through untouched rather than guessed at.
+ */
+function readPropertiesDoc(file, text) {
+    const { blocks, data } = parsePropertiesBlocks(text);
+    const serialize = (d, _targetTag, existingText) => {
+        const obj = isObj(d) ? d : newObj();
+        const baseBlocks = existingText !== undefined ? parsePropertiesBlocks(existingText).blocks : blocks;
+        const seen = new Set();
+        const lines = baseBlocks.map((b) => {
+            if (!("key" in b))
+                return b.text;
+            seen.add(b.key);
+            return `${b.prefix}${escapeProperties(typeof obj[b.key] === "string" ? obj[b.key] : "")}`;
+        });
+        for (const k of Object.keys(obj)) {
+            if (seen.has(k) || typeof obj[k] !== "string")
+                continue;
+            lines.push(`${k}=${escapeProperties(obj[k])}`);
+        }
+        return lines.join("\n");
+    };
+    return { data, serialize };
+}
 /** Android's `&entity;` plus its own backslash escapes (`\'`, `\"`, `\n`, `\t`) and `<![CDATA[...]]>`. */
 function unescapeAndroidXml(s) {
     return s
@@ -906,6 +1020,8 @@ export function readLocaleDoc(file, tag, isSource = false, fuzzy = false) {
         return readArbDoc(file, text);
     if (ext === ".strings")
         return readStringsDoc(file, text);
+    if (ext === ".properties")
+        return readPropertiesDoc(file, text);
     if (ext === ".xml")
         return readAndroidXmlDoc(file, text);
     if (ext === ".xcstrings")

package/package.json

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