@blocofy/cli 0.11.0 → 0.12.0

package/README.md

@@ -226,6 +226,43 @@ get a random UUID. Transient failures (429/502/503/504, network) are retried aga
 idempotency key, so a retry replays the same batch. Exit 0 on success (or "No changes" when
 every item was already recorded).
 
+### Translations
+
+```
+blocofy translations export --locale <tag> --out <file> [--force] [--format json|xliff] [--only all|missing|stale|pending] [--json]
+blocofy translations import <file.json|file.xlf> [--dry-run] [--publish] [--on-source-change skip|apply] [--json]
+```
+`export` writes every text of one language that needs translating (pages, image texts, records,
+menus, site settings, theme texts) to ONE file. The platform answers in windows; the command
+follows every window until the last and merges them, then lists what was left out and why.
+`--format xliff` writes XLIFF 1.2 for translation tools (the platform's own dialect, byte for
+byte); `--only pending` limits the file to texts that are missing or need an update. The export
+asks for every kind, so the API key needs the read scopes of all of them: `pages:read`,
+`content:read`, `navigation:write` (menus have no read scope), `settings:read`, `themes:read` and
+`models:read`; a key without one of them is refused for the whole export. An existing `--out` file
+is never replaced silently: the command refuses before any request unless `--force` is given, and
+the file is written through a temporary file and a rename.
+
+`import` reads a JSON or XLIFF package, drops empty translations, and sends the rest as JSON in
+chunks of at most 500 units (a page or record is never split; one group of up to 5,000 units is
+sent whole). Every chunk is checked locally before the first request. It prints the count per
+state (written, unchanged, empty, source changed, target changed, invalid, blocked). New pages and
+records are created as drafts and page content goes to the draft; menus, site settings, theme texts,
+a live record's text and a live page's title and SEO texts change at once (a live page's URL only
+with `--publish`, once that page's publish succeeded). `--publish` also publishes the pages and records this
+import wrote (needs `pages:write` and `content:write`) and reports what could not be published;
+`--dry-run` writes nothing and reports what would change. The API key needs the write scopes of
+the kinds in the package. A refusal (for example an invalid text) exits 2 with the server's error
+JSON on stderr; if a later chunk fails, the chunks already written stay written, the report of
+those chunks (counts, what was published or held back, a failed cache refresh) is printed before the
+error (`--json`: one object with `"stopped": true` on stdout), and running the command again is safe
+(written texts answer "unchanged"). Transient failures (429/502/503/504, network) are retried, except
+for a chunk imported with `--publish`: a resend could not see what the first attempt already
+published, so such a chunk is sent once. A 5xx or a lost connection stops the command with
+`TRANSLATIONS_IMPORT_OUTCOME_UNKNOWN` (exit 1), naming the chunk that may or may not have been
+applied and published; a 429 stops it with `TRANSLATIONS_IMPORT_NOT_APPLIED` (exit 1), since that
+chunk was not applied.
+
 ### Settings
 
 ```
@@ -408,10 +445,26 @@ Retries: network errors and HTTP 429/502/503/504 are retried up to 3 times (`Ret
 honoured, max 30s per wait; else 0.3s/0.9s/2s), resending the identical request (`pages push`
 carries one `x-idempotency-key` per push). HTTP 500 is never retried, nor is a `theme push` dry
 run answered 502 `readback_unverified` (a verdict on a rolled-back plan, not a transient failure).
+`translations import --publish` is never retried either: a resend could not see what the first
+attempt already published, so a failed chunk stops the command with
+`TRANSLATIONS_IMPORT_OUTCOME_UNKNOWN` (5xx, network) or `TRANSLATIONS_IMPORT_NOT_APPLIED` (429).
 Each retry prints a notice on stderr.
 
 ## Changelog
 
+- **0.12.0** — Translation packages (#925).
+  - `blocofy translations export --locale <tag> --out <file> [--format json|xliff] [--only …]`
+    writes every text of one language that needs translating to one JSON or XLIFF 1.2 file. It
+    follows every export window and lists what the platform left out, by reason.
+  - `blocofy translations import <file> [--dry-run] [--publish] [--on-source-change skip|apply]`
+    reads a JSON or XLIFF package and imports it in chunks of at most 500 units (a page or record
+    is never split, up to 5,000 units). It prints the count per state, what was published, and
+    whether the site cache could not be refreshed. A chunk imported with `--publish` is never
+    resent automatically: when it gets no definite answer the command stops with
+    `TRANSLATIONS_IMPORT_OUTCOME_UNKNOWN` (a 429: `TRANSLATIONS_IMPORT_NOT_APPLIED`), exit 1, names
+    the chunk, and running it again is safe. A run that stops part-way still prints the report of
+    the chunks done before it.
+  - `export` refuses an existing `--out` file unless `--force`.
 - **0.11.0** — One named context per site, one explicit target (customer item 1.8).
   The dev token and the v1 API key remain two separate credentials; a context references both.
   - **Breaking:** conflicting context choices now fail closed. When `BLOCOFY_CONTEXT`, the env

package/bin/blocofy.mjs

@@ -9,7 +9,7 @@
  * livereload. No monorepo required.
  */
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -49,6 +49,22 @@ import {
 import { startDevServer } from "../lib/dev-server.mjs";
 import { readLocalTemplates } from "../lib/local-theme.mjs";
 import { CliRefusal, DEFAULT_API_URL, decidePageMediaUses, fetchPageMediaUses, isValidApiKey } from "../lib/media-uses.mjs";
+import {
+  ImportNotApplied,
+  ImportOutcomeUnknown,
+  TRANSLATION_ONLY,
+  XLIFF_MAX_CHARS,
+  addImportReport,
+  chunkPackage,
+  emptyImportTally,
+  exportAllTranslations,
+  exportSkipLines,
+  fitChunksToBodyCap,
+  importSummaryLines,
+  importTranslationChunk,
+  readPackageFile,
+  toXliff,
+} from "../lib/translations.mjs";
 import { githubNote, healthAdvice, retryNotice, statusLine, syncScopeNote } from "../lib/messages.mjs";
 import { promptSecret } from "../lib/secret-prompt.mjs";
 import { MANIFEST_PATH, buildManifest, validateSiteStateTree, verifyManifest } from "../lib/site-state.mjs";
@@ -89,6 +105,8 @@ const KNOWN = {
   sitePlan: ["target", "mode", "accept-live-effects"],
   siteApply: ["target", "mode", "accept-live-effects"],
   sitePublish: ["target", "mode", "yes"],
+  translationsExport: ["locale", "out", "format", "only", "force"],
+  translationsImport: ["dry-run", "publish", "on-source-change"],
 };
 // CF-T1/T2: every command accepts the global `--context <name>` and `--json` (machine-readable refusals).
 function parseArgsOrExit(rest, known) {
@@ -270,6 +288,36 @@ Usage
       1 usage/auth/network/5xx; 2 the server refused (4xx) — the {error} JSON
       is printed to stderr.
 
+  blocofy translations export --locale <tag> --out <file> [--force] [--format json|xliff]
+                              [--only all|missing|stale|pending] [--json]
+      Write every text of one language that needs translating (pages, image texts, records,
+      menus, site settings, theme texts) to ONE file (v1 API). The export asks for every kind,
+      so the API key needs the read scopes of all of them: pages:read, content:read,
+      navigation:write (menus have no read scope), settings:read, themes:read and models:read.
+      The platform answers in windows; the command follows every window and merges them, then
+      lists what was left out and why. --format xliff writes XLIFF 1.2 for translation tools.
+        --only pending   only texts that are missing or need an update
+        --force          replace --out if it already exists (refused otherwise, before any request)
+
+  blocofy translations import <file.json|file.xlf> [--dry-run] [--publish]
+                              [--on-source-change skip|apply] [--json]
+      Import a translated package (v1 API; the write scopes of the kinds, and with --publish
+      also pages:write and content:write). Empty translations are skipped; the rest is sent in
+      chunks of at most 500 units (a page or record is never split, up to 5,000 units). Prints
+      the count per state. New pages and records are created as drafts and page content goes to
+      the draft; menus, site settings, theme texts, a live record's text and a live page's title
+      and SEO texts change at once.
+        --dry-run        write nothing; report what would change
+        --publish        also publish the pages and records this import wrote. A publishing
+                         chunk is never resent automatically: if it gets no definite answer (or a
+                         429) the command stops and says so; running it again is safe.
+        --on-source-change apply  also write texts whose source changed since the export
+                                  (default: skip)
+      If a chunk fails, the report of the chunks done before it is printed first (--json: one
+      object with "stopped": true on stdout).
+      Exit codes: 0 done; 1 usage/file/network/5xx (or a publishing chunk that was stopped);
+      2 the server refused (4xx) — the {error} JSON is printed to stderr.
+
   blocofy settings pull [dir]
   blocofy settings push [dir] (--instance <handle> | --live [--yes])
       Download / upload config/settings.json (theme tokens/settings + color schemes).
@@ -2129,6 +2177,169 @@ async function status(rest) {
   console.log("");
 }
 
+// ── translations (#925): one language's texts as a package file, and back ──────────────────────────────────
+
+const TRANSLATIONS_EXPORT_USAGE = "blocofy translations export --locale <tag> --out <file> [--force] [--format json|xliff] [--only all|missing|stale|pending] [--json]";
+const TRANSLATIONS_IMPORT_USAGE = "blocofy translations import <file.json|file.xlf> [--dry-run] [--publish] [--on-source-change skip|apply] [--json]";
+
+function usageExit(usage) {
+  console.error(`Usage: ${usage}`);
+  process.exit(1);
+}
+
+const outExists = (out) =>
+  Object.assign(new Error(`${out} already exists. Nothing was requested or written. Choose another --out file, or add --force to replace it.`), { code: "TRANSLATIONS_OUT_EXISTS", details: { file: out } });
+
+/** Write `text` to `out` through a temp file + rename, so `out` is never left half-written. */
+function writeOutFile(out, text, force) {
+  const temp = `${out}.${process.pid}.blocofy-tmp`;
+  try {
+    writeFileSync(temp, text, { flag: "wx" });
+    if (!force && existsSync(out)) throw outExists(out);
+    renameSync(temp, out);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
+}
+
+async function translationsExport(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.translationsExport);
+  const locale = typeof flags.locale === "string" ? flags.locale : null;
+  const out = typeof flags.out === "string" ? resolve(flags.out) : null;
+  const format = flags.format === undefined ? "json" : flags.format;
+  const only = flags.only === undefined ? "all" : flags.only;
+  const force = flags.force === true;
+  if (!locale || !out || positionals.length > 0 || (format !== "json" && format !== "xliff") || !TRANSLATION_ONLY.includes(only)) usageExit(TRANSLATIONS_EXPORT_USAGE);
+  // A file the customer may have filled in is never replaced silently.
+  if (!force && existsSync(out)) throw outExists(out);
+  // A read of the site; the package goes to --out, never into the project tree (so no binding is needed or written).
+  const { apiUrl, apiKey } = (await prepareTarget({ command: "translations export", commandClass: "read", dir: process.cwd(), flags, needs: "api", mode: `read · ${locale}` })).api;
+  const { pkg, skipped } = await exportAllTranslations({ apiUrl, apiKey, locale, only, onRetry, onPage: ({ page, units }) => console.error(`Export: request ${page}, ${units} unit(s) so far`) });
+  // toXliff refuses a text XML cannot carry BEFORE anything is written.
+  const text = format === "xliff" ? toXliff(pkg) : `${JSON.stringify(pkg, null, 2)}\n`;
+  writeOutFile(out, text, force);
+  if (format === "xliff" && text.length > XLIFF_MAX_CHARS) {
+    console.error(`Warning: this XLIFF file is over ${XLIFF_MAX_CHARS.toLocaleString("en-US")} characters and cannot be imported back. Export with --format json, or a smaller scope such as --only pending.`);
+  }
+  if (flags.json) {
+    console.log(JSON.stringify({ file: out, format, target_locale: pkg.target_locale, units: pkg.units.length, skipped }));
+    return;
+  }
+  console.log(`Exported ${pkg.units.length} unit(s) for ${pkg.target_locale} to ${out} (${format === "xliff" ? "XLIFF" : "JSON"}).`);
+  const skipLines = exportSkipLines(skipped);
+  if (skipLines.length > 0) {
+    console.log("Left out:");
+    for (const line of skipLines) console.log(`  - ${line}`);
+  }
+}
+
+/** The one `--json` shape of an import run: complete, stopped part-way, or with nothing to send. */
+function importJson(tally, { dryRun, publish, locale, chunks, chunksDone, caches, splitGroups, stopped }) {
+  return {
+    dry_run: dryRun,
+    target_locale: locale,
+    chunks,
+    chunks_done: chunksDone,
+    stopped,
+    counts: tally.counts,
+    created: tally.created,
+    stamped: tally.stamped,
+    publication: !dryRun && publish ? { published: tally.published, blocked: tally.publishBlocked } : null,
+    publish_skipped: tally.publishSkipped,
+    notes: tally.notes,
+    hints: tally.hints,
+    cache: caches,
+    split_groups: splitGroups,
+  };
+}
+
+async function translationsImport(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.translationsImport);
+  const onSourceChange = flags["on-source-change"] === undefined ? "skip" : flags["on-source-change"];
+  if (positionals.length !== 1 || (onSourceChange !== "skip" && onSourceChange !== "apply")) usageExit(TRANSLATIONS_IMPORT_USAGE);
+  const file = resolve(positionals[0]);
+  const dryRun = flags["dry-run"] === true;
+  const publish = flags.publish === true;
+  // Everything local is checked before the first request: the file, its chunks, every chunk's body size.
+  let pkg;
+  let chunked;
+  try {
+    pkg = readPackageFile(readFileSync(file, "utf8"), file);
+    chunked = chunkPackage(pkg);
+    chunked.chunks = fitChunksToBodyCap(chunked.chunks);
+  } catch (error) {
+    console.error(`Cannot read translation package ${file}: ${String(error?.message ?? error).replace(/\.?$/, ".")} Nothing was sent.`);
+    process.exit(1);
+  }
+  const { chunks, skippedEmpty, splitGroups } = chunked;
+  let tally = emptyImportTally();
+  tally.counts.skipped_empty += skippedEmpty;
+  const caches = [];
+  let done = 0;
+  const shape = { dryRun, publish, locale: pkg.target_locale, chunks: chunks.length, caches, splitGroups };
+  if (chunks.length === 0) {
+    if (flags.json) console.log(JSON.stringify(importJson(tally, { ...shape, chunksDone: 0, stopped: false })));
+    else console.log("Every translation in the file is empty; nothing to import. Nothing was sent.");
+    return;
+  }
+  const mode = `${dryRun ? "dry run" : publish ? "write + publish" : "write"} · ${pkg.target_locale}`;
+  const { apiUrl, apiKey } = (await prepareTarget({ command: "translations import", commandClass: dryRun ? "read" : "remote-mutation", dir: process.cwd(), flags, needs: "api", mode })).api;
+  try {
+    for (const chunk of chunks) {
+      const answer = await importTranslationChunk({ apiUrl, apiKey, chunk, dryRun, publish, onSourceChange, onRetry });
+      tally = addImportReport(tally, answer);
+      if (answer?.cache !== undefined && answer.cache !== null) caches.push(answer.cache);
+      done += 1;
+      if (chunks.length > 1) console.error(`${dryRun ? "Checked" : "Imported"} ${done} of ${chunks.length} chunks`);
+    }
+  } catch (error) {
+    // What the chunks before the failure did (published pages, held drafts, a failed cache flush) is reported in
+    // full: a rerun answers `unchanged` for them and could never tell it again.
+    if (done > 0) {
+      if (flags.json) console.log(JSON.stringify(importJson(tally, { ...shape, chunksDone: done, stopped: true })));
+      else {
+        console.log(`Report for the ${done} of ${chunks.length} chunks done before the stop:`);
+        for (const line of importSummaryLines(tally, { dryRun, publish, locale: pkg.target_locale, splitGroups })) console.log(line);
+      }
+    }
+    if (!JSON_MODE) {
+      const invalid = error instanceof CliRefusal && Array.isArray(error.error?.details?.units) ? error.error.details.units : [];
+      if (invalid.length > 0) {
+        console.error("These texts were refused; fix the file and import again:");
+        for (const u of invalid.slice(0, 20)) console.error(`  ${u.id}: ${u.message ?? u.reason ?? "refused"}`);
+        if (invalid.length > 20) console.error(`  …and ${invalid.length - 20} more.`);
+      }
+      if (!dryRun && done > 0) {
+        console.error(`Import stopped after ${done} of ${chunks.length} chunks. The chunks before it were saved; running the same command again is safe (units already applied report as unchanged).`);
+      }
+    }
+    const details = { chunk: done + 1, chunks: chunks.length, reason: error?.reason };
+    if (error instanceof ImportOutcomeUnknown) {
+      throw Object.assign(
+        new Error(
+          `The import of chunk ${done + 1} of ${chunks.length} got no definite answer (${error.reason}) and was not resent, because it publishes: that chunk may or may not have been applied and published. Running the same command again is safe (units already applied report as unchanged).`,
+        ),
+        { code: "TRANSLATIONS_IMPORT_OUTCOME_UNKNOWN", details },
+      );
+    }
+    if (error instanceof ImportNotApplied) {
+      throw Object.assign(
+        new Error(
+          `The import of chunk ${done + 1} of ${chunks.length} was refused (${error.reason}, too many requests) and was not applied; it was not resent, because it publishes. Wait a moment and run the same command again (units already applied report as unchanged).`,
+        ),
+        { code: "TRANSLATIONS_IMPORT_NOT_APPLIED", details },
+      );
+    }
+    throw error;
+  }
+  if (flags.json) {
+    console.log(JSON.stringify(importJson(tally, { ...shape, chunksDone: done, stopped: false })));
+    return;
+  }
+  for (const line of importSummaryLines(tally, { dryRun, publish, locale: pkg.target_locale, splitGroups })) console.log(line);
+}
+
 const [first, ...rest] = args;
 
 function commandKey(a, b) {
@@ -2163,6 +2374,8 @@ const COMMANDS = {
   "site plan": sitePlan,
   "site apply": siteApply,
   "site publish": sitePublish,
+  "translations export": translationsExport,
+  "translations import": translationsImport,
 };
 
 if (first === "--version" || first === "-v") {

package/lib/args.mjs

@@ -8,8 +8,9 @@
  * Sonraki token'ı değer olarak almayan flag'ler. 0.8.0: `api-key` de boolean'dır — `login --api-key`
  * gizli prompt açar; `--api-key <değer>` sözdizimi bilerek YOKTUR (sır argv'ye ve shell geçmişine girmez).
  * CF-T1: `--keychain` (login) ve `--adopt` (link) de değersizdir. CF-T3: `--force` (pages push) da; gerekçesi `--reason <text>`.
+ * #925: `--publish` (translations import) da değersizdir.
  */
-const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json", "strict", "write", "keychain", "adopt", "force"]);
+const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json", "strict", "write", "keychain", "adopt", "force", "publish"]);
 
 /**
  * `known`: bu komutun kabul ettiği bayrak adları (Set). Verildiğinde bilinmeyen bir `--x`