@chesterbrains/translify-cli 0.3.0 → 0.4.1

package/README.md

@@ -77,9 +77,7 @@ npx translify pull
 }
 ```
 
-- `pattern` must contain `{locale}`. `{namespace}` is optional; without it, set a fixed `"namespace"` on the rule.
-- `format` is `json`, `xliff` or `arb`. JSON also takes `"jsonStyle": "nested"` (default) or `"flat"`.
-- `locales` maps a locale name on disk to the Translify locale code, for example `{ "en_US": "en-US" }`. Omit it when the names already match.
+Every field is described in the [`translify.json` reference](#translifyjson-reference).
 
 ## Quickstart: Flutter
 
@@ -117,6 +115,26 @@ 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.
 
+## `translify.json` reference
+
+`translify.json` lives in the repository root; every command reads it from the current directory. The
+[JSON schema](schema/translify.schema.json) gives editors completion and validation through `$schema`. Unknown
+fields are refused, and so is any field whose name contains `key`, `secret` or `token`: keys never go in this file.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `$schema` | string | no | Schema URL for editor support. Ignored by the CLI. |
+| `apiUrl` | URL | yes | The Translify API base, ending in `/api`, e.g. `https://translify.tommasofeltrin.work/api`. |
+| `files` | array | yes | One rule per kind of translation file. Each rule has the fields below. |
+| `files[].pattern` | string | yes | Path relative to `translify.json`, with `/` separators. Must contain `{locale}` once and may contain `{namespace}` once, e.g. `locales/{locale}/{namespace}.json`. |
+| `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": "…" }`. |
+| `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;
+otherwise the CLI stops before sending anything and names the files involved.
+
 ## Commands
 
 | Command | What it does |
@@ -133,7 +151,7 @@ Options:
 
 - `push`: `--dry-run`, `--overwrite-targets`, `--prune`, `-y/--yes`, `--namespace <ns>`, `--status <draft|needs-review|approved>`
 - `pull` and `status`: `--from <working|env:slug>`, `--locale <locale>` (as named on disk), `--namespace <ns>`, `--only-approved`
-- `publish`: `--fail-on-withheld`
+- `publish`: `--fail-on-withheld`, `--allow-errors`
 - `lint`: `--namespace <ns>`, `--locale <locale>` (as named on disk), `--severity <error|warning>` (only list cells whose worst issue is this severity; counts and the exit code are unaffected), `--max-warnings <n>`
 - `--json` on `push`, `pull`, `status`, `publish` and `lint`: machine-readable output on stdout
 - `--debug` (global): print error details and stack traces
@@ -145,10 +163,44 @@ Options:
 - **Source locale: your files win.** Existing source translations are overwritten with what is in the file.
 - **Target locales: Translify fills only the gaps.** Keys that already have a translation are left alone and counted as skipped.
 - `--overwrite-targets` also overwrites existing target translations.
-- `--prune` deletes keys that no longer exist in your source files, together with their translations. Keys that are published to an environment are never deleted: they are listed as kept, and you unpublish them in Translify first. `--prune` deletes exactly the keys you confirmed: the real push sends a digest of the dry run's list, and if anything changed since (keys added, removed or published) the server refuses and you re-run `translify push --prune` to review the new list. A server too old to return that digest makes `--prune` refuse.
+- `--prune` deletes keys that no longer exist in your source files, together with their translations. See [Prune safety](#prune-safety).
 - `--yes` skips the confirmation prompt for the two destructive flags. Without a terminal and without `--yes`, a destructive push is refused and nothing changes.
 - `--dry-run` shows the effect of any combination and writes nothing.
 
+## Prune safety
+
+`translify push --prune` is the only command that deletes keys. What it deletes, and what stops it:
+
+- **Only the namespaces in this push.** A key is an orphan when its namespace is in the push and its source file no
+  longer has it. Namespaces you did not push (another rule, another repository, `--namespace` left them out) are never
+  touched.
+- **Never published keys.** A key published to any environment is listed as kept and survives. Unpublish it in
+  Translify first if it really should go.
+- **Never a whole namespace by accident.** If a source file in the push has no entries, the push is refused
+  (`VALIDATION_FAILED` with `emptySourcePrune`) instead of deleting every key in that namespace. Emptying a namespace
+  is done in the Translify web app.
+- **Exactly the list you confirmed.** The CLI always runs a dry run first, shows the keys it would delete and asks
+  for confirmation. The real push sends a digest of that list; if the server's list differs by then (keys added,
+  removed or published in between), it refuses with `ORPHANS_CHANGED` and writes nothing. A server too old to return
+  the digest makes `--prune` refuse.
+- **No silent prune in CI.** Without a terminal, `--prune` is refused unless you pass `--yes`.
+- **Atomic.** The whole push, deletions included, is one transaction: if anything fails, nothing is written.
+
+`--yes` confirms whatever that run's dry run lists, so in CI review the list before it runs unattended. One way:
+show the orphans on pull requests and prune on `main`.
+
+```yaml
+# on pull_request: list what a prune would delete, change nothing
+- run: npx translify push --prune --dry-run
+  env:
+    TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
+
+# on push to main: prune for real
+- run: npx translify push --prune --yes
+  env:
+    TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
+```
+
 ## Review
 
 When the project has **Require review** turned on in Translify:
@@ -156,6 +208,7 @@ When the project has **Require review** turned on in Translify:
 - `push` lands target-locale translations it writes as **needs review**. `--status draft` or `--status needs-review` picks the status explicitly, and `--status approved` approves them as they land. The source file is always approved. Each locale row shows the status its cells landed in, and the output counts approved translations that went back to review because this push changed their source text.
 - Without review, `push` approves everything it writes, and `--status draft` / `--status needs-review` are refused (`REVIEW_DISABLED`).
 - `publish` to an environment with **Publish approved text only** ships the last approved text of each translation. The output adds how many translations were **carried over** (the approved text went out instead of a newer, unapproved edit) and how many were **withheld** (never approved, so left out). Publishing still succeeds; `--fail-on-withheld` exits 5 when anything was withheld, for pipelines that must ship everything reviewed.
+- `publish` refuses when a translation that would go live has a placeholder error (a missing or extra placeholder, invalid ICU, a printf type mismatch). Nothing is published, the refused translations are listed like `lint` lists them, and the command exits 6. Warnings never block. On an environment with **Publish approved text only**, only approved translations count: one carried over from its last approved text never blocks. `--allow-errors` publishes anyway and reports how many went out with errors; the publish is recorded in the activity log with the override.
 - `pull --only-approved` writes the approved text from the working copy and leaves out translations that were never approved, for building a release bundle without publishing. `status --only-approved` compares against the same. It works with `--from working` only: environments already apply the gate.
 
 ## CI (GitHub Actions)
@@ -234,7 +287,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 | `lint` found placeholder errors, or more warnings than `--max-warnings` |
+| 6 | Placeholder errors: `lint` found them (or more warnings than `--max-warnings`), or `publish` refused because translations with errors would go live |
 
 The server's error `code` decides the exit code first; the HTTP status is only used for codes the CLI does not know.
 
@@ -261,6 +314,7 @@ The server's error `code` decides the exit code first; the HTTP status is only u
 | `ORPHANS_CHANGED` | 1 | The orphan list changed between the dry run and the real push (keys were added, removed or published). Nothing was written; run `translify push --prune` again to review the new list. |
 | `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). |
 | `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/publish.js

@@ -1,15 +1,37 @@
-import { EXIT } from '../errors.js';
+import { CliError, EXIT } from '../errors.js';
+import { renderIssueCells } from '../render.js';
+const isInvalidCells = (details) => typeof details === 'object' && details !== null && details.code === 'INVALID_CELLS';
+/** The server's one-line refusal, the cells grouped like `lint`, and the way out. */
+const refusal = (body, config) => {
+    const cells = Array.isArray(body.cells) ? body.cells : [];
+    const lines = [
+        `Publish refused: ${body.total} translation(s) with placeholder errors would go live. Nothing was published.`,
+        ...renderIssueCells(cells, config),
+    ];
+    if (body.total > cells.length)
+        lines.push(`Showing first ${cells.length} of ${body.total}.`);
+    lines.push('Fix them (translify lint lists every issue) or re-run with --allow-errors.');
+    return new CliError(EXIT.issues, lines.join('\n'), body);
+};
 export async function runPublish(environment, deps) {
-    const res = await deps.api.post('/cli/v1/publish', { environment });
+    // Only send the flag when it is set: a server older than the gate rejects unknown fields.
+    const request = deps.allowErrors === true ? { environment, allowErrors: true } : { environment };
+    const res = await deps.api.post('/cli/v1/publish', request).catch((error) => {
+        if (error instanceof CliError && isInvalidCells(error.details))
+            throw refusal(error.details, deps.config);
+        throw error;
+    });
     const carriedOverCount = res.carriedOverCount ?? 0;
     const withheldCount = res.withheldCount ?? 0;
+    const errorCount = res.errorCount ?? 0;
     // An ungated environment reports 0 / 0; keep its output as it was before review state.
     const gate = carriedOverCount > 0 || withheldCount > 0 ? ` ${carriedOverCount} carried over, ${withheldCount} withheld.` : '';
+    const errors = errorCount > 0 ? ` ${errorCount} with placeholder errors.` : '';
     deps.out(deps.json === true
         ? JSON.stringify({
             response: res,
-            summary: { environment, publishedCount: res.publishedCount, carriedOverCount, withheldCount },
+            summary: { environment, publishedCount: res.publishedCount, carriedOverCount, withheldCount, errorCount },
         })
-        : `Published ${res.publishedCount} translation(s) to ${environment}.${gate}`);
+        : `Published ${res.publishedCount} translation(s) to ${environment}.${gate}${errors}`);
     return deps.failOnWithheld === true && withheldCount > 0 ? EXIT.withheld : EXIT.ok;
 }

package/dist/http.js

@@ -8,7 +8,7 @@ const REQUEST_TIMEOUT_MS = 180_000;
 const UPGRADE = 'npm i -g @chesterbrains/translify-cli@latest, or for the standalone binary: curl -fsSL https://github.com/chesterbrains/translify-cli/releases/latest/download/install.sh | sh';
 const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Exit code by the body's `code` first; the status only decides for a code we do not know. */
-const CODE_EXIT = {
+export const CODE_EXIT = {
     VALIDATION_FAILED: EXIT.failed,
     LOCALE_NOT_FOUND: EXIT.failed,
     NAMESPACE_NOT_FOUND: EXIT.failed,
@@ -32,6 +32,7 @@ const CODE_EXIT = {
     RATE_LIMITED: EXIT.network,
     REVIEW_DISABLED: EXIT.failed,
     APPROVED_ONLY_REQUIRES_WORKING: EXIT.failed,
+    INVALID_CELLS: EXIT.issues,
 };
 const exitFor = (status, code) => {
     const byCode = code === undefined ? undefined : CODE_EXIT[code];
@@ -88,6 +89,8 @@ const describeBody = (status, body) => {
             return 'Review is off for this project, so --status draft or needs-review cannot be used. Turn on "Require review" in the project settings, or drop --status.';
         case 'APPROVED_ONLY_REQUIRES_WORKING':
             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 'TRANSACTION_CONFLICT':
             return 'The server hit a transaction conflict. Try again.';
         case 'RATE_LIMITED':

package/dist/index.js

@@ -106,13 +106,17 @@ program
     .command('publish <environment>')
     .description('Publish an environment')
     .option('--fail-on-withheld', 'exit 5 when the review gate withheld any translation (the publish still happens)')
+    .option('--allow-errors', 'publish even when translations with placeholder errors would go live (otherwise refused, exit 6)')
     .option('--json', 'machine-readable output')
     .action(async (environment, opts) => {
+    const { api, config } = await withApi();
     process.exitCode = await runPublish(environment, {
-        api: (await withApi()).api,
+        api,
+        config,
         out,
         json: opts.json,
         failOnWithheld: opts.failOnWithheld,
+        allowErrors: opts.allowErrors,
     });
 });
 program

package/dist/render.js

@@ -109,14 +109,11 @@ const cut = (value) => (value.length > MAX_VALUE ? `${value.slice(0, MAX_VALUE -
  * ESLint-style: namespace, then key, then one line per issue with the locale as named on disk.
  * Rows arrive sorted by the server; only the grouping headers are added here.
  */
-export function renderLint(res, config, view = {}) {
-    const { errors, warnings } = res.summary;
-    if (errors + warnings === 0)
-        return pc.green(`✔ No issues in ${res.summary.locales.length} locale(s).`);
+export function renderIssueCells(cells, config) {
     const lines = [];
     let namespace;
     let key;
-    for (const cell of res.cells) {
+    for (const cell of cells) {
         if (cell.namespace !== namespace) {
             namespace = cell.namespace;
             key = undefined;
@@ -126,14 +123,22 @@ export function renderLint(res, config, view = {}) {
             key = cell.key;
             lines.push(`  ${key}`);
         }
-        const locale = toFsLocale(cell.locale, config).padEnd(8);
+        const locale = (config === undefined ? cell.locale : toFsLocale(cell.locale, config)).padEnd(8);
         for (const issue of cell.issues) {
             const label = issue.severity === 'ERROR' ? pc.red('error'.padEnd(8)) : pc.yellow('warning'.padEnd(8));
             lines.push(`    ${locale} ${label} ${issueText(issue)}`);
-            if (issue.code === 'ICU_INVALID')
+            if (issue.code === 'ICU_INVALID' && cell.value !== undefined) {
                 lines.push(`${VALUE_INDENT}${pc.dim(JSON.stringify(cut(cell.value)))}`);
+            }
         }
     }
+    return lines;
+}
+export function renderLint(res, config, view = {}) {
+    const { errors, warnings } = res.summary;
+    if (errors + warnings === 0)
+        return pc.green(`✔ No issues in ${res.summary.locales.length} locale(s).`);
+    const lines = renderIssueCells(res.cells, config);
     if (res.truncated) {
         const matched = view.severity === 'error' ? errors : view.severity === 'warning' ? warnings : errors + warnings;
         lines.push(pc.yellow(`Showing first ${res.cells.length} of ${matched} cells. Narrow with --namespace / --locale, or use --json.`));

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.3.0';
+export const VERSION = '0.4.1';
 export const USER_AGENT = `translify-cli/${VERSION}`;

package/package.json

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