@chesterbrains/translify-cli 0.4.1 → 0.5.0

package/README.md

@@ -9,6 +9,8 @@ The CLI reads a `translify.json` that maps your translation files (i18next JSON,
 - `status` to fail CI when local files differ from Translify,
 - `publish` an environment.
 
+Complete example apps — React + i18next at runtime, Flutter (ARB) and Angular (XLIFF) at build time — live in [translify-examples](https://github.com/chesterbrains/translify-examples).
+
 ## Install
 
 ### Standalone binary (no Node needed)
@@ -115,6 +117,46 @@ 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).
+
 ## `translify.json` reference
 
 `translify.json` lives in the repository root; every command reads it from the current directory. The
@@ -130,6 +172,7 @@ 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` | no | Only for `xliff`. Writes `@angular/localize` placeholders on pull (`<ph equiv="INTERPOLATION"/>`, `{VAR_PLURAL, …}`) and reads `ng extract-i18n` output on push. See [Angular (XLIFF)](#angular-xliff). |
 | `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;
@@ -287,7 +330,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.
 
@@ -315,6 +358,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 as Angular XLIFF (text beside a plural, nested plurals, number/date formats, printf 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). |
 | `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) => {
+    const cells = Array.isArray(body.cells) ? body.cells : [];
+    const lines = [
+        `Pull refused: ${body.total} translation(s) cannot be written as Angular XLIFF. 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,8 @@ 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 (opts.from !== undefined)
             query.from = opts.from;
         if (opts.onlyApproved)
@@ -60,7 +76,11 @@ 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);
+            throw error;
+        });
         responses.push(res);
         for (const warning of res.warnings) {
             lines.push(`warning: ${warning}`);

package/dist/commands/push.js

@@ -20,6 +20,7 @@ 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 } : {}),
     }))));
     form.set('dryRun', String(dryRun));
     form.set('overwriteTargets', String(opts.overwriteTargets === true));

package/dist/config.js

@@ -17,6 +17,7 @@ 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']).optional(),
 })
     .strict()
     .superRefine((rule, ctx) => {
@@ -30,6 +31,9 @@ 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"' });
+    }
 })
     .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,36 @@ 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',
+};
+/** 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.1';
+export const VERSION = '0.5.0';
 export const USER_AGENT = `translify-cli/${VERSION}`;

package/package.json

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

package/schema/translify.schema.json

@@ -28,7 +28,11 @@
             "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"],
+            "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."
+          }
         },
         "allOf": [
           {
@@ -42,6 +46,10 @@
           {
             "if": { "properties": { "format": { "enum": ["xliff", "arb"] } }, "required": ["format"] },
             "then": { "not": { "required": ["jsonStyle"] } }
+          },
+          {
+            "if": { "properties": { "format": { "enum": ["json", "arb"] } }, "required": ["format"] },
+            "then": { "not": { "required": ["xliffDialect"] } }
           }
         ]
       }