@chesterbrains/translify-cli 0.4.2 → 0.6.0

package/README.md

@@ -117,6 +117,89 @@ flutter gen-l10n
 
 `"@@locale"` is optional in ARB files: when it is absent, the file's locale is used. When it is present it must match the file's locale (case and `_`/`-` are ignored). On `pull`, the CLI writes `@@locale` using the locale name on disk (for example `en_US` in `app_en_US.arb`), as `flutter gen-l10n` expects.
 
+## Angular (XLIFF)
+
+Angular's `@angular/localize` writes a template interpolation as an inline `<ph>` element and a template ICU as
+`{VAR_PLURAL, …}` / `{VAR_SELECT, …}`, and matches a translation's placeholders by the `equiv` name. Plain ICU text
+(`Hello, {name}`) in an Angular XLIFF is therefore literal text at build time. Set `xliffDialect` on the rule and the
+server converts both ways:
+
+```json
+{ "files": [{ "pattern": "src/locale/messages.{locale}.xlf", "format": "xliff", "namespace": "web", "xliffDialect": "angular" }] }
+```
+
+Give every template string `i18n="@@<key>"` so the unit ids are your keys. What `pull` writes:
+
+| Translify value | Angular unit |
+|---|---|
+| `Hello, {name}` | `Hello, <ph id="0" equiv="INTERPOLATION" disp="{{ name }}"/>` |
+| `{a} {b} {a}` | ids `0`, `1`, `2`; `equiv` `INTERPOLATION`, `INTERPOLATION_1`, `INTERPOLATION` (one name per distinct argument, in order of first appearance in the source; a translation reuses the source's names however it reorders them) |
+| `{count, plural, one {{count} item} other {# items}}` (the whole message) | `{VAR_PLURAL, plural, one {<ph id="0" equiv="INTERPOLATION" disp="{{ count }}"/> item} other {<ph id="1" equiv="INTERPOLATION" disp="{{ count }}"/> items}}` |
+| `{g, select, male {he} other {they}}` (the whole message) | `{VAR_SELECT, select, male {he} other {they}}` |
+
+What `push` reads from `ng extract-i18n --format=xlf2` output:
+
+| Angular | Translify argument |
+|---|---|
+| `<ph equiv="INTERPOLATION" disp="{{ name }}"/>` | `{name}` |
+| `disp="{{ count() }}"`, `disp="{{ user.name }}"`, `disp="{{ price | currency }}"` | the head identifier: `{count}`, `{user}`, `{price}` (also through `!.` and `[…]`); two that collide become `{user}` and `{user_2}` |
+| no usable `disp` | `{p0}`, `{p1}`, … from the `equiv` number |
+| `VAR_PLURAL` / `VAR_SELECT` | named after the first interpolation inside its branches, else `count` / `value` |
+
+Units Angular hashes for a message that mixes text with an ICU are dropped, and `<note category="location">` is not a
+description. After a round trip `#` comes back as `{count}`, and a plural or select with no interpolation inside keeps
+`count` / `value` as its argument.
+
+Not supported in this version (the pull is refused with `XLIFF_DIALECT_UNSUPPORTED`, the push reports the unit): text
+beside a plural or select, two ICUs in one message, a plural or select inside another, `selectordinal`, `number` /
+`date` / `time` formats, a quoted literal brace (`'{'`), HTML inside a message, and keys whose placeholders are printf or
+i18next rather than ICU. Give
+such a key its own element so the ICU is the whole message, or move it to a JSON rule. A complete example is the
+Angular app in [translify-examples](https://github.com/chesterbrains/translify-examples).
+
+## Xcode (XLIFF)
+
+Xcode exports and imports **XLIFF 1.2** (`<trans-unit>`), keeps printf placeholders (`%@`, `%lld`) literal, and spreads one
+String Catalog entry over several units for plurals and substitutions. Set `xliffDialect: "xcode"` and `xliffOriginal` on the
+rule and the server converts both ways; Translify keeps ICU, so the same catalog serves React, Flutter, Angular and iOS, and
+iOS translations get placeholder validation (Xcode's own import accepts a target that lost its `%@` without a word).
+
+```json
+{ "files": [{ "pattern": "Localization/{locale}.xliff", "format": "xliff", "namespace": "ios",
+              "xliffDialect": "xcode", "xliffOriginal": "Sources/App/Localizable.xcstrings" }] }
+```
+
+Workflow:
+
+1. Seed once: `xcodebuild -exportLocalizations -localizationPath out -exportLanguage en`, copy
+   `out/en.xcloc/Localized Contents/en.xliff` to `Localization/en.xliff`, `translify push`.
+2. Translate in Translify, then `translify pull`.
+3. `xcodebuild -importLocalizations -localizationPath Localization/it.xliff` (a bare `.xliff` works; `<file original>`
+   comes from `xliffOriginal`).
+
+What `pull` writes (arguments are positional, numbered by first appearance in the source, so a reordered translation keeps
+its meaning; the printf type comes from the push that created the key, else `%@` for text, `%lld` for a plural's count, `%f`
+for a fraction):
+
+| Translify value | Units |
+|---|---|
+| `Hello, {name}` | `key` → `Hello, %1$@` |
+| `{count, plural, one {# item} other {# items}}` | `key\|==\|plural.one` → `%1$lld item`, `key\|==\|plural.other` → `%1$lld items` |
+| `You have {count, plural, one {# item} other {# items}} in your cart, {name}` | `key` → `You have %1$#@count@ in your cart, %2$@`, plus `key\|==\|substitutions.count.plural.one` / `.other` |
+| untranslated | the unit has a `<source>` and no `<target>`, which Xcode shows as untranslated |
+
+What `push` reads: `%@` / `%1$@` → `{arg1}` (renamed to the key's own argument when the key already exists), `%lld` →
+`{arg2}` or `#` inside a plural, `%.2f` → `{arg, number}`, `%%` → `%`; `|==|plural.*` units → one ICU plural named `count`;
+a `%#@name@` substitution → the plural inside the sentence. The printf types are kept in the key's metadata for the next
+pull. Device variations (`|==|device.*`), unknown unit kinds and legacy `.strings`/`.stringsdict` exports are reported as
+`unsupportedVariation` and skipped.
+
+Not supported in this version (the pull is refused with `XLIFF_DIALECT_UNSUPPORTED`): `select` and `selectordinal`, exact
+matches (`=0`) and `offset`, two plurals in one message, nested plurals, number formats without a known printf type (e.g.
+currency), a translation whose shape differs from the source (plain text for a plural), and keys whose
+placeholders are printf or i18next rather than ICU. A complete example is `examples/ios-xcstrings` in
+[translify-examples](https://github.com/chesterbrains/translify-examples).
+
 ## `translify.json` reference
 
 `translify.json` lives in the repository root; every command reads it from the current directory. The
@@ -132,6 +215,8 @@ fields are refused, and so is any field whose name contains `key`, `secret` or `
 | `files[].format` | `json` \| `xliff` \| `arb` | yes | File format: i18next JSON, XLIFF or Flutter ARB. |
 | `files[].namespace` | string | when the pattern has no `{namespace}`, and always for `arb` | Fixed namespace for every file the rule matches. Lowercase kebab-case, at most 64 characters. |
 | `files[].jsonStyle` | `nested` \| `flat` | no | Only for `json`. `nested` (the default) writes `{ "a": { "b": "…" } }`, `flat` writes `{ "a.b": "…" }`. |
+| `files[].xliffDialect` | `angular` \| `xcode` | no | Only for `xliff`. `angular` writes `@angular/localize` placeholders on pull and reads `ng extract-i18n` output on push ([Angular (XLIFF)](#angular-xliff)); `xcode` writes XLIFF 1.2 for String Catalogs and reads `xcodebuild -exportLocalizations` output ([Xcode (XLIFF)](#xcode-xliff)). |
+| `files[].xliffOriginal` | string | with `xliffDialect: "xcode"` | The String Catalog path Xcode knows, e.g. `Sources/App/Localizable.xcstrings`; written to `<file original>`. Xcode imports nothing when it does not match the project. Only with `xcode`. |
 | `locales` | object | no | Maps a locale name on disk to a Translify locale code, e.g. `{ "en_US": "en-US" }`. Unmapped names pass through unchanged. Two names may not map to the same code, and a target may not itself be a mapped name. |
 
 Each file must be matched by one rule only, and each (locale, namespace) pair must come from one file only;
@@ -289,7 +374,7 @@ Pull and publish on deploy:
 | 3 | Plan quota exceeded |
 | 4 | Network failure, server error, push too large, CLI too old, transaction conflict, or rate limited after 3 retries |
 | 5 | `publish --fail-on-withheld`: the publish went through, but the review gate withheld some translations |
-| 6 | Placeholder errors: `lint` found them (or more warnings than `--max-warnings`), or `publish` refused because translations with errors would go live |
+| 6 | Placeholder errors: `lint` found them (or more warnings than `--max-warnings`), `publish` refused because translations with errors would go live, or `pull` refused an Angular XLIFF rule |
 
 The server's error `code` decides the exit code first; the HTTP status is only used for codes the CLI does not know.
 
@@ -317,6 +402,7 @@ The server's error `code` decides the exit code first; the HTTP status is only u
 | `REVIEW_DISABLED` | 1 | `push --status draft` or `--status needs-review` on a project without review. Turn on **Require review** in the project settings, or drop `--status`. Nothing was written. |
 | `APPROVED_ONLY_REQUIRES_WORKING` | 1 | `--only-approved` was combined with `--from env:<slug>`. Pull an environment without it; it already holds only what its gate allowed. |
 | `INVALID_CELLS` | 6 | `publish` refused: translations that would go live have placeholder errors. Nothing was published; the output lists them like `lint` does. Fix them in Translify, or re-run with `--allow-errors` to publish anyway (recorded in the activity log). |
+| `XLIFF_DIALECT_UNSUPPORTED` | 6 | `pull` refused: a translation cannot be written in the rule's XLIFF dialect (Angular: text beside a plural, nested plurals, number/date formats; Xcode: `select`, `=0`/`offset`, a translation of a different shape; both: printf/i18next keys). Nothing was written; the output lists the cells and why. Split the text, or move the key to a JSON rule. See [Angular (XLIFF)](#angular-xliff) and [Xcode (XLIFF)](#xcode-xliff). |
 | `TRANSACTION_CONFLICT` | 4 | Another write collided with yours. Retry. |
 | `RATE_LIMITED` | 4 | The CLI already retried 3 times, honouring `Retry-After`. Wait a moment and retry. |
 | `INTERNAL_ERROR` / `DATABASE_ERROR` / 5xx | 4 | A server problem. Retry shortly; if it persists, re-run with `--debug` and report it. |

package/dist/commands/pull.js

@@ -2,8 +2,22 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { CliError, EXIT, ONLY_APPROVED_NEEDS_WORKING } from '../errors.js';
 import { pathFor, toFsLocale, toTranslifyLocale } from '../patterns.js';
+import { renderReasonCells } from '../render.js';
 const readOrUndefined = async (path) => readFile(path, 'utf8').catch(() => undefined);
 const NESTED_CONFLICT = /nested JSON cannot hold both/;
+const isDialectUnsupported = (details) => typeof details === 'object' && details !== null && details.code === 'XLIFF_DIALECT_UNSUPPORTED';
+/** The server's one-line refusal, the cells grouped like `lint`, and the way out. */
+const dialectRefusal = (body, config, dialect) => {
+    const cells = Array.isArray(body.cells) ? body.cells : [];
+    const lines = [
+        `Pull refused: ${body.total} translation(s) cannot be written as XLIFF for ${dialect}. Nothing was written.`,
+        ...renderReasonCells(cells, config),
+    ];
+    if (body.total > cells.length)
+        lines.push(`Showing first ${cells.length} of ${body.total}.`);
+    lines.push('Split the text so each key is plain text with placeholders or one plural/select, or move the key to a JSON rule.');
+    return new CliError(EXIT.issues, lines.join('\n'), body);
+};
 /**
  * Flutter's gen_l10n requires `@@locale` to match the file name, and only the CLI knows the disk
  * mapping. Rewrites the value in place (key order kept) with the server's own formatting so the
@@ -51,6 +65,10 @@ export async function runPull(opts, deps) {
         const query = { format: rule.format };
         if (rule.format === 'json' && rule.jsonStyle !== undefined)
             query.jsonStyle = rule.jsonStyle;
+        if (rule.format === 'xliff' && rule.xliffDialect !== undefined)
+            query.dialect = rule.xliffDialect;
+        if (rule.format === 'xliff' && rule.xliffOriginal !== undefined)
+            query.original = rule.xliffOriginal;
         if (opts.from !== undefined)
             query.from = opts.from;
         if (opts.onlyApproved)
@@ -60,7 +78,12 @@ export async function runPull(opts, deps) {
         const namespace = rule.namespace ?? opts.namespace;
         if (namespace !== undefined)
             query.namespaces = namespace;
-        const res = await deps.api.get('/cli/v1/pull', query);
+        const res = await deps.api.get('/cli/v1/pull', query).catch((error) => {
+            if (error instanceof CliError && isDialectUnsupported(error.details)) {
+                throw dialectRefusal(error.details, deps.config, rule.xliffDialect ?? 'angular');
+            }
+            throw error;
+        });
         responses.push(res);
         for (const warning of res.warnings) {
             lines.push(`warning: ${warning}`);

package/dist/commands/push.js

@@ -20,6 +20,8 @@ const buildForm = (uploads, opts, dryRun, prune, pruneDigest) => {
         format: match.rule.format,
         locale: match.locale,
         namespace: match.namespace,
+        ...(match.rule.format === 'xliff' && match.rule.xliffDialect !== undefined ? { dialect: match.rule.xliffDialect } : {}),
+        ...(match.rule.format === 'xliff' && match.rule.xliffOriginal !== undefined ? { original: match.rule.xliffOriginal } : {}),
     }))));
     form.set('dryRun', String(dryRun));
     form.set('overwriteTargets', String(opts.overwriteTargets === true));
@@ -73,6 +75,9 @@ export async function runPush(opts, deps) {
         bytes: new Uint8Array(await readFile(join(deps.cwd, match.path))),
     })));
     const show = (res, preview) => {
+        if (opts.json !== true)
+            for (const warning of res.warnings ?? [])
+                deps.out(`warning: ${warning}`);
         deps.out(opts.json === true
             ? JSON.stringify({ preview, response: res, summary: summarizePush(res) })
             : renderPush(res, { prune: opts.prune === true }));

package/dist/config.js

@@ -17,6 +17,8 @@ const fileRule = z
     format: z.enum(['json', 'xliff', 'arb']),
     namespace: z.string().regex(NAMESPACE, 'must be lowercase kebab-case').max(64).optional(),
     jsonStyle: z.enum(['nested', 'flat']).optional(),
+    xliffDialect: z.enum(['angular', 'xcode']).optional(),
+    xliffOriginal: z.string().min(1).max(512).optional(),
 })
     .strict()
     .superRefine((rule, ctx) => {
@@ -30,6 +32,15 @@ const fileRule = z
     if (rule.jsonStyle !== undefined && rule.format !== 'json') {
         ctx.addIssue({ code: 'custom', path: ['jsonStyle'], message: 'only applies to format "json"' });
     }
+    if (rule.xliffDialect !== undefined && rule.format !== 'xliff') {
+        ctx.addIssue({ code: 'custom', path: ['xliffDialect'], message: 'only applies to format "xliff"' });
+    }
+    if (rule.xliffOriginal !== undefined && rule.xliffDialect !== 'xcode') {
+        ctx.addIssue({ code: 'custom', path: ['xliffOriginal'], message: 'only applies to xliffDialect "xcode"' });
+    }
+    if (rule.xliffDialect === 'xcode' && rule.xliffOriginal === undefined) {
+        ctx.addIssue({ code: 'custom', path: ['xliffOriginal'], message: 'required with xliffDialect "xcode"' });
+    }
 })
     .transform((rule) => (rule.format === 'json' ? { ...rule, jsonStyle: rule.jsonStyle ?? 'nested' } : rule));
 const configSchema = z

package/dist/http.js

@@ -33,6 +33,7 @@ export const CODE_EXIT = {
     REVIEW_DISABLED: EXIT.failed,
     APPROVED_ONLY_REQUIRES_WORKING: EXIT.failed,
     INVALID_CELLS: EXIT.issues,
+    XLIFF_DIALECT_UNSUPPORTED: EXIT.issues,
 };
 const exitFor = (status, code) => {
     const byCode = code === undefined ? undefined : CODE_EXIT[code];
@@ -91,6 +92,8 @@ const describeBody = (status, body) => {
             return ONLY_APPROVED_NEEDS_WORKING;
         case 'INVALID_CELLS':
             return `Publish refused: ${String(body.total)} translation(s) with placeholder errors would go live. Nothing was published.`;
+        case 'XLIFF_DIALECT_UNSUPPORTED':
+            return `Pull refused: ${String(body.total)} translation(s) cannot be written as Angular XLIFF. Nothing was written.`;
         case 'TRANSACTION_CONFLICT':
             return 'The server hit a transaction conflict. Try again.';
         case 'RATE_LIMITED':

package/dist/render.js

@@ -134,6 +134,39 @@ export function renderIssueCells(cells, config) {
     }
     return lines;
 }
+const REASON_TEXT = {
+    mixedIcu: 'text next to a plural or select (Angular needs the whole message to be the ICU)',
+    multipleIcu: 'more than one plural or select in one message',
+    nestedIcu: 'a plural or select inside another one',
+    ordinal: 'selectordinal has no Angular equivalent',
+    invalidIcu: 'does not parse as ICU',
+    formattedArg: 'a number, date or time format has no Angular placeholder',
+    literalBrace: "a quoted literal brace ('{') cannot be loaded by Angular",
+    syntax: 'the key uses printf or i18next placeholders, not ICU',
+    exactMatch: 'an exact match (=0, =1) or offset has no Xcode plural category',
+    shapeMismatch: 'the translation is not the same shape as the source (plural vs plain text, or a different plural argument)',
+    unsupportedVariation: 'a device variation or an unknown |==| unit (not supported)',
+};
+/** Like renderIssueCells: namespace, key, then one line per cell with the locale as named on disk. */
+export function renderReasonCells(cells, config) {
+    const lines = [];
+    let namespace;
+    let key;
+    for (const cell of cells) {
+        if (cell.namespace !== namespace) {
+            namespace = cell.namespace;
+            key = undefined;
+            lines.push(pc.bold(namespace));
+        }
+        if (cell.key !== key) {
+            key = cell.key;
+            lines.push(`  ${key}`);
+        }
+        const locale = (config === undefined ? cell.locale : toFsLocale(cell.locale, config)).padEnd(8);
+        lines.push(`    ${locale} ${pc.red('error'.padEnd(8))} ${REASON_TEXT[cell.reason] ?? cell.reason}`);
+    }
+    return lines;
+}
 export function renderLint(res, config, view = {}) {
     const { errors, warnings } = res.summary;
     if (errors + warnings === 0)

package/dist/version.js

@@ -1,3 +1,3 @@
 // Must equal package.json "version"; src/version.test.ts fails when they drift.
-export const VERSION = '0.4.2';
+export const VERSION = '0.6.0';
 export const USER_AGENT = `translify-cli/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chesterbrains/translify-cli",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Push, pull and publish Translify translations from your repository",
   "license": "MIT",
   "repository": {

package/schema/translify.schema.json

@@ -28,7 +28,17 @@
             "maxLength": 64,
             "description": "Fixed namespace. Required when the pattern has no {namespace}, and always for arb."
           },
-          "jsonStyle": { "enum": ["nested", "flat"], "description": "Only for format json. Defaults to nested." }
+          "jsonStyle": { "enum": ["nested", "flat"], "description": "Only for format json. Defaults to nested." },
+          "xliffDialect": {
+            "enum": ["angular", "xcode"],
+            "description": "Only for format xliff. angular writes @angular/localize placeholders (<ph equiv=\"INTERPOLATION\"/>, VAR_PLURAL) on pull and reads ng extract-i18n output on push. xcode writes XLIFF 1.2 for String Catalogs (positional printf, |==| plural and substitution units) and reads xcodebuild -exportLocalizations output."
+          },
+          "xliffOriginal": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "description": "Only with xliffDialect xcode, and required with it: the String Catalog path Xcode knows (e.g. Sources/App/Localizable.xcstrings), written to <file original>. Xcode imports nothing when it does not match."
+          }
         },
         "allOf": [
           {
@@ -42,6 +52,15 @@
           {
             "if": { "properties": { "format": { "enum": ["xliff", "arb"] } }, "required": ["format"] },
             "then": { "not": { "required": ["jsonStyle"] } }
+          },
+          {
+            "if": { "properties": { "format": { "enum": ["json", "arb"] } }, "required": ["format"] },
+            "then": { "not": { "required": ["xliffDialect"] } }
+          },
+          {
+            "if": { "properties": { "xliffDialect": { "const": "xcode" } }, "required": ["xliffDialect"] },
+            "then": { "required": ["xliffOriginal"] },
+            "else": { "not": { "required": ["xliffOriginal"] } }
           }
         ]
       }