locale-ai 0.6.16 → 0.6.17

package/README.md

@@ -30,13 +30,14 @@ Download 577 MB? (Y/n)
 
 - **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.
 - **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.
 - **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. Rails-style nested plurals (`item:` with `one:`/`other:` children instead of `item_one`/`item_other`) get the same missing-forms treatment — Android's `<plurals>`/`<item quantity="...">` groups are the same shape and get it too.
+- **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. Rails-style nested plurals (`item:` with `one:`/`other:` children instead of `item_one`/`item_other`) get the same missing-forms treatment — Android's `<plurals>`/`<item quantity="...">` groups and `.xcstrings`' `variations.plural` are the same shape and get it too.
 - **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.
+**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.
 
 ## Why locale-ai?
 

package/dist/cli.js

@@ -34,7 +34,8 @@ Translate options:
   --from <locale>       Source locale (default: en)
   --to <locales>        Target locale(s), comma separated: fr,es,pt-BR
   --input <dir>         Folder containing <from>/ or <from>.json/.yaml/.yml/.po/.pot/.arb/.strings,
-                        or an Android res/ folder (values/strings.xml) (auto-detected)
+                        an Android res/ folder (values/strings.xml) (auto-detected),
+                        or a path straight to a .xcstrings catalog (not auto-detected)
   --overwrite           Re-translate strings that already have a translation
   --dry-run             Show what would be translated without downloading or writing
   --fast                Greedy decoding: ~2x faster, slightly lower quality
@@ -173,8 +174,10 @@ async function cmdTranslate(argv) {
     const sources = sourceFiles(layout, from.tag).map((f) => ({ file: f, doc: readLocaleDoc(f, from.tag, true, values.fuzzy) }));
     const singularHints = new Set(sources.flatMap(({ doc }) => [...pluralOneStrings(doc.data)]));
     log(`locale-ai ${VERSION}`);
-    log(`Found ${sources.length} ${from.tag} file${sources.length === 1 ? "" : "s"} in ${rel(layout.root)}/` +
-        (layout.kind === "dir" ? `${from.tag}${layout.dirSuffix ?? ""}/` : ""));
+    log(layout.kind === "xcstrings"
+        ? `Found ${from.tag} strings in ${rel(layout.file)}`
+        : `Found ${sources.length} ${from.tag} file${sources.length === 1 ? "" : "s"} in ${rel(layout.root)}/` +
+            (layout.kind === "dir" ? `${from.tag}${layout.dirSuffix ?? ""}/` : ""));
     let failures = 0;
     const jobs = [];
     for (const locale of targets) {

package/dist/locales.js

@@ -102,6 +102,20 @@ export function detectLayout(cwd, from, input) {
         if (path.basename(abs) === "values" && isFile(path.join(abs, "strings.xml"))) {
             return { kind: "android", root: path.dirname(abs) };
         }
+        if (abs.endsWith(".xcstrings") && isFile(abs)) {
+            let raw;
+            try {
+                raw = JSON.parse(readText(abs));
+            }
+            catch (e) {
+                throw new Error(`Invalid .xcstrings (JSON) in ${input}: ${e.message}`);
+            }
+            const sourceLanguage = raw?.sourceLanguage;
+            if (typeof sourceLanguage === "string" && sourceLanguage !== from) {
+                throw new Error(`${input} has sourceLanguage "${sourceLanguage}", not "${from}" — pass --from ${sourceLanguage}.`);
+            }
+            return { kind: "xcstrings", root: path.dirname(abs), file: abs };
+        }
         const base = path.basename(abs);
         const directExt = EXTENSIONS.find((ext) => base === `${from}${ext}`);
         if (directExt && isFile(abs))
@@ -139,6 +153,8 @@ function listLocaleFiles(dir) {
 export function sourceFiles(layout, from) {
     if (layout.kind === "android")
         return [path.join(layout.root, "values", "strings.xml")];
+    if (layout.kind === "xcstrings")
+        return [layout.file];
     return layout.kind === "dir"
         ? listLocaleFiles(path.join(layout.root, dirNameFor(layout, from)))
         : [path.join(layout.root, fileNameFor(layout, from, layout.ext))];
@@ -148,6 +164,8 @@ const outputExt = (ext) => (ext === ".pot" ? ".po" : ext);
 export function targetFile(layout, from, to, src) {
     if (layout.kind === "android")
         return path.join(layout.root, `values-${androidQualifier(to)}`, "strings.xml");
+    if (layout.kind === "xcstrings")
+        return layout.file;
     if (layout.kind === "file")
         return path.join(layout.root, fileNameFor(layout, to, outputExt(layout.ext)));
     const rel = path.relative(path.join(layout.root, dirNameFor(layout, from)), src);
@@ -166,6 +184,25 @@ function looksLikeLocale(tag) {
 }
 /** Locale tags already translated alongside `from` in this layout (for `locale-ai check`). */
 export function existingTargets(layout, from) {
+    if (layout.kind === "xcstrings") {
+        let raw;
+        try {
+            raw = JSON.parse(readText(layout.file));
+        }
+        catch {
+            return [];
+        }
+        const strings = isObj(raw) && isObj(raw.strings) ? raw.strings : {};
+        const tags = new Set();
+        for (const entry of Object.values(strings)) {
+            if (!isObj(entry) || !isObj(entry.localizations))
+                continue;
+            for (const tag of Object.keys(entry.localizations))
+                tags.add(tag);
+        }
+        tags.delete(from);
+        return [...tags].filter(looksLikeLocale).sort();
+    }
     if (layout.kind === "android") {
         return fs
             .readdirSync(layout.root, { withFileTypes: true })
@@ -478,6 +515,119 @@ function readArbDoc(file, text) {
     };
     return { data, serialize };
 }
+/** True when `entry` uses a per-device variant (`variations.iphone`/`.ipad`/...) for `tag`, not just a plural. */
+function xcstringsHasDeviceVariant(entry) {
+    const locs = entry.localizations;
+    if (!isObj(locs))
+        return false;
+    return Object.values(locs).some((loc) => isObj(loc) && isObj(loc.variations) && Object.keys(loc.variations).some((k) => k !== "plural"));
+}
+/** `shouldTranslate: false`, multi-variable `substitutions`, or any per-device variant — left untouched. */
+function xcstringsSkip(entry) {
+    return !isObj(entry) || entry.shouldTranslate === false || entry.substitutions !== undefined || xcstringsHasDeviceVariant(entry);
+}
+/** An entry's value for one locale: a plain string, a `{zero,one,...}` plural object, or undefined if untranslated. */
+function xcstringsValue(entry, tag) {
+    const loc = entry.localizations?.[tag];
+    if (!loc)
+        return undefined;
+    const plural = loc.variations?.plural;
+    if (plural) {
+        const out = newObj();
+        for (const cat of CATEGORIES) {
+            const v = plural[cat]?.stringUnit?.value;
+            if (typeof v === "string")
+                out[cat] = v;
+        }
+        return Object.keys(out).length ? out : undefined;
+    }
+    const v = loc.stringUnit?.value;
+    return typeof v === "string" ? v : undefined;
+}
+/**
+ * Apple's `.xcstrings` String Catalog (Xcode 15+'s default, replacing `.strings`):
+ * unlike every other format here, ALL locales — source included — live in ONE JSON
+ * file, keyed by the string's own identifier under `strings`. Each entry's
+ * `localizations.<tag>` holds either a plain `stringUnit` or, for a plural string, a
+ * `variations.plural` object whose zero/one/two/few/many/other categories are exactly
+ * the shape `addNestedPluralForms` already understands (see Android/Rails), so it's
+ * reused unchanged. An entry with no `localizations.<sourceLanguage>` at all falls
+ * back to its own key as the source text, matching Xcode's own convention for a
+ * string that was never given explicit source content.
+ *
+ * `shouldTranslate: false`, Xcode's per-device variants (`variations.iphone`/`.ipad`),
+ * and multi-variable strings (`substitutions`, used with `%#@name@`-style format
+ * references) are all left completely untouched rather than mistranslated — a bigger
+ * matrix than a single cardinal plural isn't supported yet.
+ *
+ * `targetFile`/`sourceFiles` point every locale at this same one file, so each
+ * locale's turn re-reads it fresh (via `existingText`) before writing — the same
+ * read-then-write-fresh sequencing the CLI already does per locale, which is what
+ * lets several locales share one file safely in a single run without clobbering each
+ * other. A key's translated value is only ever replaced, never its `state`/metadata,
+ * when the value hasn't actually changed — so a translator's own "needs_review" flag
+ * on an untouched entry survives a rerun.
+ */
+function readXcstringsDoc(file, text, tag, isSource) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`Invalid .xcstrings (JSON) in ${file}: ${e.message}`);
+    }
+    const strings = isObj(raw.strings) ? raw.strings : {};
+    const data = newObj();
+    for (const key of Object.keys(strings)) {
+        const entry = strings[key];
+        if (xcstringsSkip(entry))
+            continue;
+        const v = xcstringsValue(entry, tag);
+        if (v !== undefined)
+            data[key] = v;
+        else if (isSource)
+            data[key] = key;
+    }
+    const indent = /^\{\r?\n([ \t]+)/.exec(text)?.[1] ?? 2;
+    const keepNewline = finalNewline(text);
+    const serialize = (d, targetTag, existingText) => {
+        const obj = isObj(d) ? d : newObj();
+        let out = raw;
+        if (existingText !== undefined) {
+            try {
+                out = JSON.parse(existingText);
+            }
+            catch {
+                out = raw;
+            }
+        }
+        const outStrings = isObj(out.strings) ? out.strings : (out.strings = newObj());
+        for (const key of Object.keys(obj)) {
+            const entry = outStrings[key];
+            if (xcstringsSkip(entry))
+                continue;
+            const newVal = obj[key];
+            const curVal = xcstringsValue(entry, targetTag);
+            if (JSON.stringify(curVal) === JSON.stringify(newVal))
+                continue;
+            const locs = isObj(entry.localizations) ? entry.localizations : (entry.localizations = newObj());
+            if (isObj(newVal)) {
+                const plural = newObj();
+                for (const cat of CATEGORIES) {
+                    if (typeof newVal[cat] === "string") {
+                        plural[cat] = { stringUnit: { state: "translated", value: newVal[cat] } };
+                    }
+                }
+                locs[targetTag] = { variations: { plural } };
+            }
+            else if (typeof newVal === "string") {
+                locs[targetTag] = { stringUnit: { state: "translated", value: newVal } };
+            }
+        }
+        return withNewline(JSON.stringify(out, null, indent), keepNewline);
+    };
+    return { data, serialize };
+}
 const poKey = (e) => (e.msgctxt ?? "") + "\u0004" + e.msgid;
 /**
  * gettext's well-established Plural-Forms formulas, keyed by language. Copying the
@@ -758,6 +908,8 @@ export function readLocaleDoc(file, tag, isSource = false, fuzzy = false) {
         return readStringsDoc(file, text);
     if (ext === ".xml")
         return readAndroidXmlDoc(file, text);
+    if (ext === ".xcstrings")
+        return readXcstringsDoc(file, text, tag, isSource);
     return readJsonDoc(file, text);
 }
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);

package/package.json

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