@quaso-i18n/cli 1.0.0-rc.2 → 1.0.0-rc.2.main.g0b25541

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quaso-i18n/cli",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.2.main.g0b25541",
   "description": "The command line of Quaso, localization for i18next JSON files: upload, download, status and import, from a laptop, from CI and for AI agents",
   "license": "MIT",
   "type": "module",

package/quaso.mjs

@@ -1073,6 +1073,16 @@ var CHECKS = {
   identical: "warning",
   /** The numbers differ from the English. */
   numbers_differ: "warning",
+  /** An HTML or i18next Trans tag, such as `<b>` or `<1>`, is missing or extra. */
+  tags_differ: "warning",
+  /** Spaces or line breaks at the start or the end differ from the English. */
+  edge_whitespace: "warning",
+  /** The number of line breaks inside the text differs from the English. */
+  line_breaks_differ: "warning",
+  /** Two spaces in a row, which the English doesn't have. */
+  double_space: "warning",
+  /** Ends with a different question mark, exclamation mark, ellipsis or colon. */
+  end_punctuation: "warning",
   /** A glossary translation or a term marked never translate is missing. */
   glossary: "warning"
 };
@@ -1208,7 +1218,11 @@ var QuasoConfig = s.object({
     minItems: 1
   }),
   limits: s.array(LengthLimit).optional().describe("Maximum lengths, such as for app store fields (FMT-4). They win over limits set on the website."),
-  pluralExclusions: s.array(PluralExclusion).optional()
+  pluralExclusions: s.array(PluralExclusion).optional(),
+  untranslated: s.enum([
+    "source",
+    "omit"
+  ]).optional().describe("What download writes for untranslated strings: the source text (default) or nothing, for apps that fall back to the source language themselves")
 });
 
 // packages/core/src/api.ts
@@ -1310,7 +1324,11 @@ var FileVersionQuery = s.object({
 var ExportQuery = s.object({
   languages: s.array(LanguageTag).optional(),
   files: s.array(FilePath).optional(),
-  at: PublicationTime.optional()
+  at: PublicationTime.optional(),
+  untranslated: s.enum([
+    "source",
+    "omit"
+  ]).optional().describe("Untranslated entries as the English (default) or left out")
 });
 var ImportRequest = s.object({
   language: LanguageTag,
@@ -1323,6 +1341,7 @@ var ImportRequest = s.object({
   ]),
   overwrite: s.boolean().optional().describe("Also replace blue (proofread) translations"),
   keepIdentical: s.boolean().optional().describe("Keep values identical to the English"),
+  allowQaErrors: s.boolean().optional().describe("Import values that fail the quality checks, flagged, instead of refusing them"),
   dryRun: s.boolean().optional()
 });
 var JobScope = s.object({
@@ -1332,6 +1351,7 @@ var JobScope = s.object({
     maxItems: 5e3
   }).optional().describe("Only these strings"),
   retranslate: s.boolean().optional().describe("Also re-translate green strings (never blue ones, LLM-4)"),
+  qa: s.boolean().optional().describe("Also re-translate the green translations that fail the quality checks"),
   outdated: s.boolean().optional().describe("Update outdated green translations and propose updates for outdated blue ones (default true)"),
   instruction: s.string({
     maxLength: 4e3
@@ -1602,7 +1622,31 @@ var ProjectSettings = s.object({
     suffix: s.string({
       minLength: 1,
       maxLength: 10
-    })
+    }),
+    extra: s.array(s.object({
+      prefix: s.string({
+        minLength: 1,
+        maxLength: 10
+      }),
+      suffix: s.string({
+        minLength: 1,
+        maxLength: 10
+      })
+    }), {
+      maxItems: 10
+    }).optional().describe("Delimiters of placeholders the app fills in itself, such as { and } for {name}"),
+    optional: s.array(s.object({
+      placeholder: s.string({
+        minLength: 1,
+        maxLength: 100
+      }),
+      languages: s.array(LanguageTag, {
+        minItems: 1,
+        maxItems: 200
+      })
+    }), {
+      maxItems: 50
+    }).optional().describe("Placeholders some languages may leave out, such as {article}")
   }),
   logoUrl: s.string({
     maxLength: 2e3
@@ -1767,7 +1811,7 @@ var ReviewLanguageRequestRequest = s.object({
 // package.json
 var package_default = {
   name: "quaso-workspace",
-  version: "1.0.0-rc.2",
+  version: "1.0.0-rc.2.main.g0b25541",
   private: true,
   type: "module",
   license: "MIT",
@@ -2431,6 +2475,8 @@ var LONG_TIMEOUT_MS = 5 * 6e4;
 var MAX_RETRIES = 3;
 var BASE_DELAY_MS = 500;
 var MAX_RETRY_AFTER_MS = 6e4;
+var WAKE_POLL_MS = 2e3;
+var MAX_WAKE_MS = 3 * 6e4;
 var ApiClient = class {
   baseUrl;
   #apiKey;
@@ -2439,6 +2485,7 @@ var ApiClient = class {
   #random;
   #now;
   #log;
+  #awake;
   constructor(options) {
     this.baseUrl = options.baseUrl;
     this.#apiKey = options.apiKey;
@@ -2448,6 +2495,7 @@ var ApiClient = class {
     this.#now = options.now ?? Date.now;
     this.#log = options.log ?? (() => {
     });
+    this.#awake = options.waitWhileAsleep ? null : Promise.resolve();
   }
   get(path, options = {}) {
     return this.request("GET", path, {
@@ -2472,12 +2520,61 @@ var ApiClient = class {
     }
     return url.toString();
   }
+  /**
+   * Asks `/wake` until the server is up, saying so every 15 seconds. Any other answer than
+   * a start in progress (a server without `/wake`, an error) ends the wait: the requests
+   * that follow report their own problems.
+   */
+  async #waitWhileAsleep() {
+    const started = this.#now();
+    let reported = -Infinity;
+    while (this.#now() - started < MAX_WAKE_MS) {
+      const start = await this.#askWake();
+      if (start === null) return;
+      if (this.#now() - reported >= 15e3) {
+        const elapsed = Math.round(start.elapsedMs / 1e3);
+        const expected = Math.round(start.expectedMs / 1e3);
+        this.#log(`Waking up the instance: ${elapsed} s of about ${expected} s.`);
+        reported = this.#now();
+      }
+      await this.#sleep(WAKE_POLL_MS);
+    }
+  }
+  /** The start in progress, or null when the server is up or `/wake` says nothing. */
+  async #askWake() {
+    try {
+      const response = await this.#fetch(`${this.baseUrl}/wake`, {
+        headers: {
+          Accept: "application/json",
+          "User-Agent": USER_AGENT
+        },
+        redirect: "manual",
+        signal: AbortSignal.timeout(TIMEOUT_MS)
+      });
+      const json2 = response.headers.get("Content-Type")?.includes("application/json");
+      if (!response.ok || !json2) {
+        await response.body?.cancel().catch(() => {
+        });
+        return null;
+      }
+      const answer = await response.json();
+      const starting = answer?.state === "starting" && typeof answer.elapsedMs === "number" && typeof answer.expectedMs === "number";
+      return starting ? {
+        elapsedMs: answer.elapsedMs,
+        expectedMs: answer.expectedMs
+      } : null;
+    } catch {
+      return null;
+    }
+  }
   async request(method, path, options) {
     const url = this.url(path, options.query);
     const policy = options.retry ?? (method === "GET" ? "safe" : "once");
     const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
     const headers = requestHeaders(this.#apiKey, options.body !== void 0);
     const body = options.body === void 0 ? void 0 : JSON.stringify(options.body);
+    this.#awake ??= this.#waitWhileAsleep();
+    await this.#awake;
     for (let attempt = 0; ; attempt++) {
       let response;
       let text;
@@ -2610,9 +2707,9 @@ function hintFor(code, status2) {
     case "payload_too_large":
       return "Send fewer files at a time with --file.";
     case "llm_unavailable":
-      return "The instance has no LLM: its operator sets GEMINI_API_KEY.";
+      return "An administrator enters the Gemini API key in the instance's Settings \u2192 LLM translation.";
     case "budget_exceeded":
-      return "LLM translation resumes next month, or when the instance's operator raises LLM_MONTHLY_TOKEN_BUDGET.";
+      return "LLM translation resumes next month, or when an administrator raises the monthly token budget in Settings \u2192 LLM translation.";
   }
   return status2 >= 500 ? "Try again in a moment; if it persists, tell the instance's operator." : void 0;
 }
@@ -3273,6 +3370,7 @@ var Context = class {
   out;
   #fetch;
   #sleep;
+  #waitWhileAsleep;
   #project;
   #sources;
   constructor(options) {
@@ -3282,6 +3380,7 @@ var Context = class {
     this.out = options.out;
     this.#fetch = options.fetch;
     this.#sleep = options.sleep;
+    this.#waitWhileAsleep = options.waitWhileAsleep ?? true;
   }
   /** The project: `--config`, or the nearest `quaso.config.json`. */
   project() {
@@ -3311,7 +3410,8 @@ var Context = class {
       apiKey: apiKey(this.env),
       fetch: this.#fetch,
       sleep: this.#sleep,
-      log: (message) => this.out.info(message)
+      log: (message) => this.out.info(message),
+      waitWhileAsleep: this.#waitWhileAsleep
     });
   }
 };
@@ -7608,7 +7708,8 @@ var download = {
         query: {
           languages,
           files: askFiles ? wanted : void 0,
-          at
+          at,
+          untranslated: project.config.untranslated
         },
         timeoutMs: LONG_TIMEOUT_MS
       });
@@ -8006,6 +8107,11 @@ var importCommand = {
       type: "boolean",
       description: "Keep values identical to the English instead of skipping them"
     },
+    {
+      name: "allow-qa-errors",
+      type: "boolean",
+      description: "Import values that fail the quality checks, with their QA errors, instead of refusing them"
+    },
     {
       name: "dry-run",
       type: "boolean",
@@ -8062,6 +8168,7 @@ var importCommand = {
       languages: [],
       withoutFiles: [],
       refused: [],
+      flagged: [],
       unknownKeys: [],
       invalid: [],
       failed: []
@@ -8108,6 +8215,7 @@ var importCommand = {
       };
       if (flag(ctx.args, "overwrite")) request.overwrite = true;
       if (flag(ctx.args, "keep-identical")) request.keepIdentical = true;
+      if (flag(ctx.args, "allow-qa-errors")) request.allowQaErrors = true;
       if (dryRun) request.dryRun = true;
       let result;
       try {
@@ -8149,6 +8257,17 @@ var importCommand = {
           });
         }
       }
+      for (const flagged of result.flagged ?? []) {
+        for (const check of errorChecks(flagged.checks)) {
+          summary.flagged.push({
+            file: pathOf(flagged.file),
+            key: flagged.key,
+            language: flagged.language,
+            check: check.check,
+            message: checkMessage(check)
+          });
+        }
+      }
       for (const unknown of result.unknownKeys) {
         summary.unknownKeys.push({
           file: pathOf(unknown.file),
@@ -8220,8 +8339,14 @@ function renderImport(out, summary) {
     if (result.skippedIdentical > 0) {
       parts.push(`${result.skippedIdentical} identical to the English (skipped)`);
     }
+    if (result.skippedEmpty > 0) parts.push(`${result.skippedEmpty} empty (skipped)`);
+    if (result.droppedForms > 0) {
+      parts.push(`${result.droppedForms} unused plural forms dropped`);
+    }
     if (result.skippedBlue > 0) parts.push(`${result.skippedBlue} proofread kept`);
     if (result.refused.length > 0) parts.push(red(`${result.refused.length} refused`));
+    const flagged = result.flagged ?? [];
+    if (flagged.length > 0) parts.push(yellow(`${flagged.length} with QA errors`));
     if (result.unknownKeys.length > 0) parts.push(`${result.unknownKeys.length} unknown keys`);
     out.print(`${bold(result.language.padEnd(6))} ${parts.join(", ")}`);
     for (const file of result.unknownFiles) {
@@ -8246,6 +8371,7 @@ function renderImport(out, summary) {
     out.print(dim("The other languages were imported; import these again with --language."));
   }
   section("Refused by the quality checks", summary.refused);
+  section("Imported with QA errors (fix them on the instance)", summary.flagged);
   section("Keys the English doesn't have", summary.unknownKeys);
   section("Files that can't be read (fix them and import again)", summary.invalid);
   if (summary.refused.length > 0 && !summary.dryRun) {
@@ -8279,6 +8405,11 @@ var translate = {
       type: "boolean",
       description: "Also translate green (not proofread) strings again; blue ones never change"
     },
+    {
+      name: "qa",
+      type: "boolean",
+      description: "Also translate again the green strings that fail the quality checks, such as imported ones"
+    },
     {
       name: "instruction",
       type: "string",
@@ -8341,6 +8472,7 @@ var translate = {
     };
     if (files) request.files = files;
     if (flag(ctx.args, "retranslate")) request.retranslate = true;
+    if (flag(ctx.args, "qa")) request.qa = true;
     const instruction = option(ctx.args, "instruction");
     if (instruction !== void 0 && instruction.trim() !== "") request.instruction = instruction;
     const model = option(ctx.args, "model");
@@ -8427,8 +8559,17 @@ function renderEstimate(out, estimate) {
     return;
   }
   out.print(`${count(estimate.strings, "string")} (${count(estimate.words, "word")}) in ${count(estimate.requests, "request")}: about ${estimate.estimatedTokens.input.toLocaleString("en")} input and ${estimate.estimatedTokens.output.toLocaleString("en")} output tokens.`);
+  out.print(workSummary(estimate.work));
   out.print(dim("Thinking models use more tokens than this; retries add some too."));
 }
+function workSummary(work) {
+  const parts = [];
+  if (work.translate > 0) parts.push(`${work.translate} untranslated`);
+  if (work.retranslate > 0) parts.push(`${work.retranslate} green to translate again`);
+  if (work.update > 0) parts.push(`${work.update} outdated green to update`);
+  if (work.propose > 0) parts.push(`${work.propose} outdated proofread to get a proposal for review`);
+  return `Of these: ${parts.join(", ")}.`;
+}
 function renderQueued(out, job) {
   if (job.status === "done") {
     out.print("Nothing to translate: every string in scope is translated.");
@@ -8505,7 +8646,8 @@ async function run(argv, options = {}) {
       env,
       out,
       fetch: options.fetch,
-      sleep: options.sleep
+      sleep: options.sleep,
+      waitWhileAsleep: options.waitWhileAsleep
     });
     const result = await command.run(ctx);
     if (json2) out.document(resultDocument(name, result.exitCode, result.json));