@verbatra/sdk 0.2.1 → 0.3.0

package/dist/index.cjs

@@ -10,6 +10,7 @@ var deepl = require('deepl-node');
 var log = require('loglevel');
 var genai = require('@google/genai');
 var OpenAI = require('openai');
+var crypto = require('crypto');
 var promises = require('fs/promises');
 var icuMessageformatParser = require('@formatjs/icu-messageformat-parser');
 var ExcelJS = require('exceljs');
@@ -73,13 +74,16 @@ function fnv1a64(input) {
   }
   return hash.toString(16).padStart(16, "0");
 }
+function normalizeText(text) {
+  return text.normalize("NFC").replace(/\r\n?/g, "\n");
+}
 function canonicalize(entry) {
   return JSON.stringify([
-    entry.value,
-    entry.description ?? null,
-    entry.meaning ?? null,
+    normalizeText(entry.value),
+    entry.description == null ? null : normalizeText(entry.description),
+    entry.meaning == null ? null : normalizeText(entry.meaning),
     entry.isPlural,
-    [...entry.placeholders].sort()
+    [...entry.placeholders].map(normalizeText).sort()
   ]);
 }
 function contentHash(entry) {
@@ -143,17 +147,31 @@ zod.z.object({
   format: supportedFormatSchema,
   entries: zod.z.map(zod.z.string(), translationEntrySchema)
 });
-function difference(a, b) {
-  return [...new Set(a.filter((item) => !b.has(item)))].sort();
+function counts(items) {
+  const map = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    map.set(item, (map.get(item) ?? 0) + 1);
+  }
+  return map;
+}
+function multisetExcess(a, b) {
+  const excess = [];
+  for (const [token, count] of a) {
+    const surplus = count - (b.get(token) ?? 0);
+    for (let i = 0; i < surplus; i += 1) {
+      excess.push(token);
+    }
+  }
+  return excess.sort();
 }
 function sameOrder(a, b) {
   return a.length === b.length && a.every((item, index) => item === b[index]);
 }
 function checkPlaceholders(source, translated) {
-  const sourceSet = new Set(source);
-  const translatedSet = new Set(translated);
-  const missing = difference(source, translatedSet);
-  const extra = difference(translated, sourceSet);
+  const sourceCounts = counts(source);
+  const translatedCounts = counts(translated);
+  const missing = multisetExcess(sourceCounts, translatedCounts);
+  const extra = multisetExcess(translatedCounts, sourceCounts);
   const reordered = missing.length === 0 && extra.length === 0 && !sameOrder(source, translated);
   return {
     matches: missing.length === 0 && extra.length === 0 && !reordered,
@@ -295,6 +313,12 @@ async function runLlmTranslation(request, mechanism) {
   );
   return completion.usage === void 0 ? { values, integrity } : { values, integrity, usage: completion.usage };
 }
+var OUTPUT_TRUNCATED_MESSAGE = "The provider stopped because the output-token limit was reached. Reduce the batch size or raise the configured max output tokens.";
+function assertNotTruncated(truncated) {
+  if (truncated) {
+    throw new ProviderError("OUTPUT_TRUNCATED", OUTPUT_TRUNCATED_MESSAGE);
+  }
+}
 function readRequiredEnv(name) {
   const value = process.env[name];
   if (value === void 0 || value.length === 0) {
@@ -390,6 +414,7 @@ function createMechanism(client, config) {
     translate: async ({ payloadJson }) => {
       const body = buildRequest(config, payloadJson);
       const message = await callClient(client, body);
+      assertNotTruncated(message.stop_reason === "max_tokens");
       const raw = requireToolInput(message.content);
       const usage = toUsage(message.usage);
       return usage === void 0 ? { raw } : { raw, usage };
@@ -637,6 +662,7 @@ function extractGeminiResult(response) {
   if (candidate.finishReason !== void 0 && BLOCKED_FINISH_REASONS.has(candidate.finishReason)) {
     throw new ProviderError("PROVIDER_BLOCKED", "The provider filtered the translation response.");
   }
+  assertNotTruncated(candidate.finishReason === "MAX_TOKENS");
   const text = response.text;
   if (text === void 0 || text === "") {
     throw new ProviderError("INVALID_RESPONSE", "The provider returned no translation content.");
@@ -733,10 +759,12 @@ function toUsage3(usage) {
   return { inputTokens: prompt_tokens, outputTokens: completion_tokens };
 }
 function extractOpenAiResult(completion) {
-  const message = completion.choices[0]?.message;
-  if (message === void 0) {
+  const choice = completion.choices[0];
+  if (choice === void 0) {
     throw new ProviderError("INVALID_RESPONSE", "The provider returned no message.");
   }
+  assertNotTruncated(choice.finish_reason === "length");
+  const message = choice.message;
   if (message.refusal !== void 0 && message.refusal !== null && message.refusal !== "") {
     throw new ProviderError("PROVIDER_REFUSED", "The provider refused the translation request.");
   }
@@ -789,6 +817,7 @@ function buildProvider(config) {
 }
 
 // src/config/schema.ts
+var DEFAULT_MAX_BATCH_SIZE = 50;
 var verbatraConfigSchema = zod.z.strictObject({
   sourceLocale: zod.z.string().min(1),
   targetLocales: zod.z.array(zod.z.string().min(1)).min(1),
@@ -798,7 +827,31 @@ var verbatraConfigSchema = zod.z.strictObject({
   }),
   provider: providerConfigSchema,
   glossary: zod.z.record(zod.z.string(), zod.z.string()).optional(),
-  tone: zod.z.enum(["formal", "informal", "neutral"]).optional()
+  tone: zod.z.enum(["formal", "informal", "neutral"]).optional(),
+  /**
+   * Opt-in orphan pruning, off by default (absent is treated as false). When true, keys present in a
+   * target file but absent from the source (the diff's orphaned keys) are removed from the written file
+   * and the lock. A per-run `prune` option on `translate` (the CLI `--prune` flag) overrides this. This
+   * is non-secret, consistent with the config's no-secret invariant.
+   */
+  prune: zod.z.boolean().optional(),
+  /**
+   * Opt-in plural-category generation, off by default (absent is treated as false). When true, and only
+   * for an i18next-JSON project translated by an LLM provider, verbatra synthesizes the CLDR plural forms
+   * a target language requires but the source does not supply (for example Polish few/many). A per-run
+   * `generatePlurals` option on `translate` overrides this. Unsupported cases (DeepL, non-i18next, an
+   * unknown language) fall back to the per-locale plural warning.
+   */
+  generatePlurals: zod.z.boolean().optional(),
+  /**
+   * Optional maximum number of entries sent in a single provider request. A locale's missing-plus-changed
+   * entries are split into sequential sub-batches no larger than this so one oversized request cannot sink
+   * the whole locale; a failed sub-batch is withheld and retried while the others still make progress.
+   * Must be a positive integer (non-integer, zero, or negative is rejected at this boundary, never
+   * coerced). When absent, {@link DEFAULT_MAX_BATCH_SIZE} applies: 50, a conservative count that stays
+   * well inside provider context windows for typical short i18n strings while keeping request counts low.
+   */
+  maxBatchSize: zod.z.number().int().positive().optional()
 }).refine((config) => !config.targetLocales.includes(config.sourceLocale), {
   message: "targetLocales must not include the source locale",
   path: ["targetLocales"]
@@ -943,11 +996,14 @@ async function readBoundedBytes(path, maxBytes) {
     await handle.close();
   }
 }
-async function atomicWrite(path$1, data) {
-  const tmp = path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}`);
+function tempFileName(path$1) {
+  return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
+}
+async function atomicWrite(path, data) {
+  const tmp = tempFileName(path);
   await (typeof data === "string" ? promises.writeFile(tmp, data, "utf8") : promises.writeFile(tmp, data));
   try {
-    await promises.rename(tmp, path$1);
+    await promises.rename(tmp, path);
   } catch (error) {
     await promises.rm(tmp, { force: true });
     throw error;
@@ -1044,11 +1100,14 @@ async function cleanup(ops, tmp) {
   } catch {
   }
 }
-async function atomicWriteFile(path$1, data, ops = nodeOps) {
-  const tmp = path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}`);
+function tempFileName2(path$1) {
+  return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
+}
+async function atomicWriteFile(path, data, ops = nodeOps) {
+  const tmp = tempFileName2(path);
   try {
     await ops.writeFile(tmp, data);
-    await ops.rename(tmp, path$1);
+    await ops.rename(tmp, path);
   } catch (error) {
     await cleanup(ops, tmp);
     throw error;
@@ -1083,20 +1142,117 @@ async function readBounded2(filePath) {
     await handle.close();
   }
 }
-function addEntries(node, prefix, namespace, derive, out) {
+var BACKSLASH = "\\";
+var DOT = ".";
+var ESCAPED_BACKSLASH = "\\\\";
+var ESCAPED_DOT = "\\.";
+function needsEncoding(segment) {
+  return segment.includes(BACKSLASH) || segment.includes(DOT);
+}
+function encodeSegment(segment) {
+  if (!needsEncoding(segment)) {
+    return segment;
+  }
+  let out = "";
+  for (const char of segment) {
+    if (char === BACKSLASH) {
+      out += ESCAPED_BACKSLASH;
+    } else if (char === DOT) {
+      out += ESCAPED_DOT;
+    } else {
+      out += char;
+    }
+  }
+  return out;
+}
+function decodeSegment(segment) {
+  if (!segment.includes(BACKSLASH)) {
+    return segment;
+  }
+  let out = "";
+  let escaping = false;
+  for (const char of segment) {
+    if (escaping) {
+      out += char;
+      escaping = false;
+    } else if (char === BACKSLASH) {
+      escaping = true;
+    } else {
+      out += char;
+    }
+  }
+  return out;
+}
+function joinEncodedSegments(segments) {
+  return segments.join(DOT);
+}
+function decodeKeyToSegments(key) {
+  if (!key.includes(BACKSLASH)) {
+    return key.split(DOT);
+  }
+  const segments = [];
+  let current = "";
+  let escaping = false;
+  for (const char of key) {
+    if (escaping) {
+      current += BACKSLASH + char;
+      escaping = false;
+    } else if (char === BACKSLASH) {
+      escaping = true;
+    } else if (char === DOT) {
+      segments.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  if (escaping) {
+    current += BACKSLASH;
+  }
+  segments.push(current);
+  return segments.map(decodeSegment);
+}
+function addLeaf(ctx, segments, key, value) {
+  const effectivePath = segments.join(".");
+  const mapKey = joinEncodedSegments(segments.map(encodeSegment));
+  if (ctx.claimed.has(effectivePath) && ctx.claimed.get(effectivePath) !== mapKey) {
+    throw new AdapterError(
+      "INVALID_STRUCTURE",
+      "A literal dotted leaf key and a nested key path resolve to the same path."
+    );
+  }
+  ctx.claimed.set(effectivePath, mapKey);
+  const { placeholders, isPlural } = ctx.derive(key, value);
+  ctx.out.set(mapKey, { key: mapKey, namespace: ctx.namespace, value, placeholders, isPlural });
+}
+function addEntries(ctx, prefix, node) {
+  for (const [key, value] of Object.entries(node)) {
+    const segments = [...prefix, key];
+    if (typeof value === "string") {
+      addLeaf(ctx, segments, key, value);
+    } else {
+      addEntries(ctx, segments, value);
+    }
+  }
+}
+function addPathEntries(node, prefix, namespace, derive, out) {
   for (const [key, value] of Object.entries(node)) {
     const path = prefix === "" ? key : `${prefix}.${key}`;
     if (typeof value === "string") {
       const { placeholders, isPlural } = derive(key, value);
       out.set(path, { key: path, namespace, value, placeholders, isPlural });
     } else {
-      addEntries(value, path, namespace, derive, out);
+      addPathEntries(value, path, namespace, derive, out);
     }
   }
 }
-function flattenTree(tree, namespace, derive) {
+function flattenTree(tree, namespace, derive, keyMode = "literal-leaf") {
   const out = /* @__PURE__ */ new Map();
-  addEntries(tree, "", namespace, derive, out);
+  if (keyMode === "path-notation") {
+    addPathEntries(tree, "", namespace, derive, out);
+    return out;
+  }
+  addEntries({ namespace, derive, out, claimed: /* @__PURE__ */ new Map() }, [], tree);
   return out;
 }
 var jsonTreeSchema = zod.z.lazy(
@@ -1163,12 +1319,15 @@ function setPath(root, segments, value) {
   for (const segment of segments.slice(0, -1)) {
     node = descend(node, segment);
   }
+  if (typeof node[leaf] === "object") {
+    throw new AdapterError("INVALID_STRUCTURE", "A leaf key collides with a nested key path.");
+  }
   node[leaf] = value;
 }
 function unflattenEntries(entries) {
   const root = emptyNode();
   for (const [key, entry] of entries) {
-    setPath(root, key.split("."), entry.value);
+    setPath(root, decodeKeyToSegments(key), entry.value);
   }
   return root;
 }
@@ -1187,11 +1346,11 @@ function rethrowStructured(error, message) {
   }
   throw new AdapterError("INVALID_STRUCTURE", message);
 }
-function toEntries(content, namespace, deriveEntry, validateTree) {
+function toEntries(content, namespace, deriveEntry, keyMode, validateTree) {
   try {
     const tree = parseJsonObject(content);
     validateTree?.(tree);
-    return flattenTree(tree, namespace, deriveEntry);
+    return flattenTree(tree, namespace, deriveEntry, keyMode);
   } catch (error) {
     rethrowStructured(error, "The file could not be read as JSON.");
   }
@@ -1214,7 +1373,8 @@ function createJsonFileAdapter(options) {
     computeInvalidIcuKeys: computeInvalidIcuKeys2,
     validateMessage: validateMessage2,
     validateTree,
-    buildWriteTree
+    buildWriteTree,
+    keyMode = "literal-leaf"
   } = options;
   return {
     format,
@@ -1231,7 +1391,7 @@ function createJsonFileAdapter(options) {
         throw new AdapterError("INPUT_TOO_LARGE", "The file exceeds the maximum allowed size.");
       }
       const namespace = namespaceOf(filePath);
-      const entries = toEntries(outcome.content, namespace, deriveEntry, validateTree);
+      const entries = toEntries(outcome.content, namespace, deriveEntry, keyMode, validateTree);
       const resource = { locale, namespace, format, entries };
       const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys2);
       return { resource, invalidIcuKeys };
@@ -1243,23 +1403,41 @@ function createJsonFileAdapter(options) {
     }
   };
 }
-var PLACEHOLDER_PATTERN = /\{\{[^{}]*\}\}/g;
-function extractI18nextPlaceholders(value) {
-  const seen = /* @__PURE__ */ new Set();
+var DOUBLE_BRACE_PATTERN = /\{\{[^{}]*\}\}/g;
+var I18NEXT_PATTERN = /\{\{[^{}]*\}\}|\$t\([^()]*\)/g;
+function scanTokens(value, pattern) {
   const result = [];
-  for (const match of value.matchAll(PLACEHOLDER_PATTERN)) {
+  for (const match of value.matchAll(pattern)) {
     const token = match[0];
-    if (token !== void 0 && !seen.has(token)) {
-      seen.add(token);
+    if (token !== void 0) {
       result.push(token);
     }
   }
   return result;
 }
+function extractDoubleBracePlaceholders(value) {
+  return scanTokens(value, DOUBLE_BRACE_PATTERN);
+}
+function extractI18nextPlaceholders(value) {
+  return scanTokens(value, I18NEXT_PATTERN);
+}
 var PLURAL_SUFFIX = /_(zero|one|two|few|many|other)$/;
 function isPluralKey(key) {
   return PLURAL_SUFFIX.test(key);
 }
+function pluralCategoryOf(key) {
+  const match = PLURAL_SUFFIX.exec(key);
+  return match?.[1];
+}
+function pluralBaseKey(key) {
+  if (!isPluralKey(key)) {
+    return void 0;
+  }
+  return key.replace(PLURAL_SUFFIX, "");
+}
+function makePluralKey(baseKey, category) {
+  return `${baseKey}_${category}`;
+}
 function createI18nextJsonAdapter() {
   return createJsonFileAdapter({
     format: "i18next-json",
@@ -1316,16 +1494,12 @@ function analyzeIcuValue(value) {
   }
   try {
     const ast = icuMessageformatParser.parse(value);
-    const seen = /* @__PURE__ */ new Set();
     const placeholders = [];
     const state = { isPlural: false };
     collect(
       ast,
       (token) => {
-        if (!seen.has(token)) {
-          seen.add(token);
-          placeholders.push(token);
-        }
+        placeholders.push(token);
       },
       state
     );
@@ -1413,13 +1587,16 @@ async function buildNgxWriteTree(entries, filePath) {
 function createNgxTranslateJsonAdapter() {
   return createJsonFileAdapter({
     format: "ngx-translate-json",
-    extractPlaceholders: extractI18nextPlaceholders,
+    extractPlaceholders: extractDoubleBracePlaceholders,
     deriveEntry: (_key, value) => ({
-      placeholders: extractI18nextPlaceholders(value),
+      placeholders: extractDoubleBracePlaceholders(value),
       isPlural: false
     }),
     validateTree: assertNotMixed,
-    buildWriteTree: buildNgxWriteTree
+    buildWriteTree: buildNgxWriteTree,
+    // ngx-translate flat style uses dotted keys as path notation, not literal leaves;
+    // keep the legacy non-encoding flatten so its flat/nested round-trip is unchanged.
+    keyMode: "path-notation"
   });
 }
 var AdapterRegistry = class {
@@ -1470,15 +1647,13 @@ var AdapterRegistry = class {
     return this.resolveByDetection(filePath, options.sample);
   }
 };
-var PLACEHOLDER_PATTERN2 = /\{[^{}]*\}/g;
+var PLACEHOLDER_PATTERN = /(?<!\{)\{\s*([A-Za-z_][\w$-]*|\d+)\s*\}(?!\})/g;
 function extractVueI18nPlaceholders(value) {
-  const seen = /* @__PURE__ */ new Set();
   const result = [];
-  for (const match of value.matchAll(PLACEHOLDER_PATTERN2)) {
-    const token = match[0];
-    if (token !== void 0 && !seen.has(token)) {
-      seen.add(token);
-      result.push(token);
+  for (const match of value.matchAll(PLACEHOLDER_PATTERN)) {
+    const key = match[1];
+    if (key !== void 0) {
+      result.push(`{${key}}`);
     }
   }
   return result;
@@ -1540,8 +1715,10 @@ function failureSummary(locale, error) {
     translated: [],
     unchanged: [],
     orphaned: [],
+    pruned: [],
     invalidIcuSource: [],
     integrityMismatches: [],
+    generated: [],
     notices: [],
     error: describeError(error)
   };
@@ -1564,6 +1741,198 @@ function readNotices(result) {
   return candidate.filter(isNotice);
 }
 
+// src/flow/plural-categories.ts
+var LANGUAGE_CATEGORIES = {
+  ar: ["zero", "one", "two", "few", "many", "other"],
+  cy: ["zero", "one", "two", "few", "many", "other"],
+  ga: ["one", "two", "few", "many", "other"],
+  pl: ["one", "few", "many", "other"],
+  ru: ["one", "few", "many", "other"],
+  uk: ["one", "few", "many", "other"],
+  be: ["one", "few", "many", "other"],
+  lt: ["one", "few", "many", "other"],
+  sl: ["one", "two", "few", "other"]
+};
+function isKnownRicherLanguage(locale) {
+  const subtag = locale.toLowerCase().split(/[-_]/)[0] ?? "";
+  return LANGUAGE_CATEGORIES[subtag] !== void 0;
+}
+function requiredCategories(locale) {
+  const subtag = locale.toLowerCase().split(/[-_]/)[0] ?? "";
+  return LANGUAGE_CATEGORIES[subtag] ?? ["one", "other"];
+}
+function groupPluralSources(source) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const [key, entry] of source.entries) {
+    const baseKey = pluralBaseKey(key);
+    const category = pluralCategoryOf(key);
+    if (baseKey === void 0 || category === void 0) {
+      continue;
+    }
+    const group = groups.get(baseKey) ?? /* @__PURE__ */ new Map();
+    group.set(category, entry);
+    groups.set(baseKey, group);
+  }
+  return groups;
+}
+function suppliedCategories(groups) {
+  const supplied = /* @__PURE__ */ new Set();
+  for (const group of groups.values()) {
+    for (const category of group.keys()) {
+      supplied.add(category);
+    }
+  }
+  return supplied;
+}
+function detectMissingPluralCategories(source, targetLocale, format) {
+  if (format !== "i18next-json") {
+    return void 0;
+  }
+  const groups = groupPluralSources(source);
+  const supplied = suppliedCategories(groups);
+  if (supplied.size === 0) {
+    return void 0;
+  }
+  const missing = requiredCategories(targetLocale).filter((category) => !supplied.has(category));
+  if (missing.length === 0) {
+    return void 0;
+  }
+  return {
+    code: "PLURAL_CATEGORIES_INCOMPLETE",
+    message: `The source does not supply all CLDR plural categories the target language "${targetLocale}" requires (missing: ${missing.join(", ")}); verbatra translates only the source's plural forms and does not synthesize the others. Add the missing forms manually.`
+  };
+}
+function targetPluralSetIncomplete(targetKeys, targetLocale) {
+  const required = requiredCategories(targetLocale);
+  const present = /* @__PURE__ */ new Map();
+  for (const key of targetKeys) {
+    const baseKey = pluralBaseKey(key);
+    const category = pluralCategoryOf(key);
+    if (baseKey === void 0 || category === void 0) {
+      continue;
+    }
+    const set = present.get(baseKey) ?? /* @__PURE__ */ new Set();
+    set.add(category);
+    present.set(baseKey, set);
+  }
+  for (const categories of present.values()) {
+    if (required.some((category) => !categories.has(category))) {
+      return true;
+    }
+  }
+  return false;
+}
+function sourcePluralBaseKeys(source) {
+  const bases = /* @__PURE__ */ new Set();
+  for (const key of source.entries.keys()) {
+    const baseKey = pluralBaseKey(key);
+    if (baseKey !== void 0) {
+      bases.add(baseKey);
+    }
+  }
+  return bases;
+}
+function isGeneratedPluralKey(key, sourceBaseKeys) {
+  const baseKey = pluralBaseKey(key);
+  return baseKey !== void 0 && sourceBaseKeys.has(baseKey);
+}
+function pluralIncompleteNotice(targetLocale) {
+  return {
+    code: "PLURAL_CATEGORIES_INCOMPLETE",
+    message: `The plural set for the target language "${targetLocale}" is still incomplete: verbatra could not generate every required CLDR plural form (an unsupported case, or a generated form was withheld for a placeholder mismatch). Add the remaining forms manually.`
+  };
+}
+function representativeEntry(group) {
+  return group.get("other") ?? group.get("one") ?? [...group.values()][0];
+}
+function planPluralGeneration(source, targetLocale, format) {
+  if (format !== "i18next-json" || !isKnownRicherLanguage(targetLocale)) {
+    return { items: [] };
+  }
+  const required = requiredCategories(targetLocale);
+  const groups = groupPluralSources(source);
+  const items = [];
+  for (const [baseKey, group] of groups) {
+    const representative = representativeEntry(group);
+    if (representative === void 0) {
+      continue;
+    }
+    const governingEntries = [...group.values()];
+    for (const category of required) {
+      if (group.has(category)) {
+        continue;
+      }
+      items.push({
+        targetKey: makePluralKey(baseKey, category),
+        category,
+        sourceEntry: representative,
+        governingEntries
+      });
+    }
+  }
+  return { items };
+}
+
+// src/flow/plural-generation.ts
+function generatedLockHash(governingEntries, category) {
+  const governingHashes = governingEntries.map(contentHash).sort();
+  return contentHash({
+    value: `${category}:${governingHashes.join("|")}`,
+    placeholders: [],
+    isPlural: true
+  });
+}
+function syntheticEntry(item) {
+  return {
+    ...item.sourceEntry,
+    key: item.targetKey,
+    isPlural: true,
+    // The CLDR category travels as data context (the meaning field), never the instruction channel.
+    meaning: `CLDR plural category "${item.category}"`
+  };
+}
+function staleItems(items, baseline) {
+  return items.filter((item) => {
+    const hash = generatedLockHash(item.governingEntries, item.category);
+    return baseline.get(item.targetKey) !== hash;
+  });
+}
+function buildRequest2(context, entries) {
+  return {
+    sourceLocale: context.sourceLocale,
+    targetLocale: context.targetLocale,
+    entries,
+    extractPlaceholders: context.adapter.extractPlaceholders,
+    ...context.glossary !== void 0 ? { glossary: context.glossary } : {},
+    ...context.tone !== void 0 ? { tone: context.tone } : {}
+  };
+}
+async function generatePluralForms(context) {
+  const plan = planPluralGeneration(context.source, context.targetLocale, context.format);
+  const stale = staleItems(plan.items, context.baseline);
+  if (stale.length === 0) {
+    return { accepted: [], withheld: [] };
+  }
+  const entries = stale.map(syntheticEntry);
+  const result = await context.provider.translateBatch(buildRequest2(context, entries));
+  const accepted = [];
+  const withheld = [];
+  for (const item of stale) {
+    const value = result.values.get(item.targetKey);
+    const integrity = result.integrity.get(item.targetKey);
+    if (value !== void 0 && integrity?.matches === true) {
+      accepted.push({
+        targetKey: item.targetKey,
+        entry: { ...syntheticEntry(item), value },
+        lockHash: generatedLockHash(item.governingEntries, item.category)
+      });
+    } else {
+      withheld.push(item.targetKey);
+    }
+  }
+  return { accepted, withheld };
+}
+
 // src/flow/locale-run.ts
 function emptyResource(locale, format) {
   return { locale, namespace: "", format, entries: /* @__PURE__ */ new Map() };
@@ -1575,7 +1944,7 @@ async function readTarget(params) {
   }
   return (await params.adapter.read(path, params.targetLocale)).resource;
 }
-function buildRequest2(params, entries) {
+function buildRequest3(params, entries) {
   return {
     sourceLocale: params.sourceLocale,
     targetLocale: params.targetLocale,
@@ -1588,25 +1957,56 @@ function buildRequest2(params, entries) {
 async function runLocale(params) {
   const target = await readTarget(params);
   const diff = diffResources(params.source, target, { baseline: params.baseline });
+  const orphaned = params.generatePlurals ? diff.orphaned.filter((key) => !isGeneratedPluralKey(key, sourcePluralBaseKeys(params.source))) : diff.orphaned;
+  const pruned = params.prune ? orphaned : [];
   const invalidIcu = new Set(params.sourceInvalidIcuKeys);
   const candidates = [...diff.missing, ...diff.changed];
   const toTranslate = candidates.filter((key) => !invalidIcu.has(key));
   const invalidIcuSource = candidates.filter((key) => invalidIcu.has(key));
+  const pluralNotice = detectMissingPluralCategories(
+    params.source,
+    params.targetLocale,
+    params.format
+  );
+  const sdkNotices = pluralNotice ? [pluralNotice] : [];
   const provider = params.provider;
   if (provider === void 0) {
     return {
-      summary: baseSummary(params.targetLocale, diff, invalidIcuSource, toTranslate, [], []),
+      summary: baseSummary({
+        locale: params.targetLocale,
+        unchanged: diff.unchanged,
+        orphaned,
+        invalidIcuSource,
+        translated: toTranslate,
+        generated: [],
+        integrityMismatches: [],
+        pruned,
+        notices: sdkNotices
+      }),
       lockEntries: {}
     };
   }
   const entries = toTranslate.map((key) => params.source.entries.get(key)).filter((entry) => entry !== void 0);
   const accepted = /* @__PURE__ */ new Map();
   const integrityMismatches = [];
-  const notices = await translateAndCheck(provider, params, entries, accepted, integrityMismatches);
+  const subBatchNotices = await translateAndCheck(
+    provider,
+    params,
+    entries,
+    accepted,
+    integrityMismatches
+  );
   const merged = new Map(target.entries);
+  for (const key of pruned) {
+    merged.delete(key);
+  }
   for (const [key, { value, source }] of accepted) {
     merged.set(key, { ...source, value, namespace: target.namespace });
   }
+  const generation = await runGeneration(params, provider);
+  for (const form of generation.accepted) {
+    merged.set(form.targetKey, { ...form.entry, namespace: target.namespace });
+  }
   const path = localeFilePath(params.cwd, params.filesPattern, params.targetLocale);
   await params.adapter.write(
     {
@@ -1617,37 +2017,83 @@ async function runLocale(params) {
     },
     path
   );
-  const withheld = /* @__PURE__ */ new Set([...integrityMismatches, ...invalidIcuSource]);
+  const pluralNotices = params.generatePlurals ? pluralNoticeFor(params, merged) : sdkNotices;
+  const notices = [...pluralNotices, ...subBatchNotices];
+  const withheld = /* @__PURE__ */ new Set([...integrityMismatches, ...invalidIcuSource, ...generation.withheld]);
   return {
-    summary: baseSummary(
-      params.targetLocale,
-      diff,
+    summary: baseSummary({
+      locale: params.targetLocale,
+      unchanged: diff.unchanged,
+      orphaned,
       invalidIcuSource,
-      [...accepted.keys()],
-      integrityMismatches,
+      translated: [...accepted.keys()],
+      generated: generation.accepted.map((form) => form.targetKey).sort(),
+      // Withheld generated forms surface alongside withheld translations (spec D4): both failed integrity.
+      integrityMismatches: [...integrityMismatches, ...generation.withheld].sort(),
+      pruned,
       notices
-    ),
-    lockEntries: computeLockEntries(params, merged, withheld)
+    }),
+    lockEntries: computeLockEntries(params, merged, withheld, generation.accepted)
   };
 }
-function baseSummary(locale, diff, invalidIcuSource, translated, integrityMismatches, notices) {
+async function runGeneration(params, provider) {
+  if (!params.generatePlurals || provider.kind !== "llm") {
+    return { accepted: [], withheld: [] };
+  }
+  return generatePluralForms({
+    source: params.source,
+    sourceLocale: params.sourceLocale,
+    targetLocale: params.targetLocale,
+    format: params.format,
+    adapter: params.adapter,
+    provider,
+    glossary: params.glossary,
+    tone: params.tone,
+    baseline: params.baseline
+  });
+}
+function pluralNoticeFor(params, merged) {
+  if (params.format !== "i18next-json") {
+    return [];
+  }
+  if (!targetPluralSetIncomplete(merged.keys(), params.targetLocale)) {
+    return [];
+  }
+  return [pluralIncompleteNotice(params.targetLocale)];
+}
+function baseSummary(parts) {
   return {
-    locale,
+    locale: parts.locale,
     status: "succeeded",
-    translated,
-    unchanged: diff.unchanged,
-    orphaned: diff.orphaned,
-    invalidIcuSource,
-    integrityMismatches,
-    notices
+    translated: parts.translated,
+    unchanged: parts.unchanged,
+    orphaned: parts.orphaned,
+    pruned: parts.pruned,
+    invalidIcuSource: parts.invalidIcuSource,
+    integrityMismatches: parts.integrityMismatches,
+    generated: parts.generated,
+    notices: parts.notices
   };
 }
 async function translateAndCheck(provider, params, entries, accepted, integrityMismatches) {
-  if (entries.length === 0) {
-    return [];
+  const notices = [];
+  for (const batch of chunk(entries, params.maxBatchSize)) {
+    const subNotices = await runSubBatch(provider, params, batch, accepted, integrityMismatches);
+    notices.push(...subNotices);
   }
-  const result = await provider.translateBatch(buildRequest2(params, entries));
-  for (const entry of entries) {
+  return notices;
+}
+async function runSubBatch(provider, params, batch, accepted, integrityMismatches) {
+  let result;
+  try {
+    result = await provider.translateBatch(buildRequest3(params, batch));
+  } catch {
+    for (const entry of batch) {
+      integrityMismatches.push(entry.key);
+    }
+    return [subBatchFailedNotice(batch.length)];
+  }
+  for (const entry of batch) {
     const value = result.values.get(entry.key);
     const integrity = result.integrity.get(entry.key);
     if (value !== void 0 && integrity?.matches === true) {
@@ -1658,11 +2104,28 @@ async function translateAndCheck(provider, params, entries, accepted, integrityM
   }
   return readNotices(result);
 }
-function computeLockEntries(params, merged, withheld) {
+function subBatchFailedNotice(count) {
+  return {
+    code: "SUB_BATCH_FAILED",
+    message: `A sub-batch of ${count} entries failed and was withheld; it will be retried next run.`
+  };
+}
+function chunk(items, size) {
+  const chunks = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}
+function computeLockEntries(params, merged, withheld, generated) {
   const lockEntries = {};
+  const sourceBaseKeys = sourcePluralBaseKeys(params.source);
   for (const key of merged.keys()) {
     const sourceEntry = params.source.entries.get(key);
     if (sourceEntry === void 0) {
+      if (params.generatePlurals) {
+        carryGeneratedLock(lockEntries, params.baseline, key, sourceBaseKeys);
+      }
       continue;
     }
     if (withheld.has(key)) {
@@ -1674,8 +2137,20 @@ function computeLockEntries(params, merged, withheld) {
     }
     lockEntries[key] = contentHash(sourceEntry);
   }
+  for (const form of generated) {
+    lockEntries[form.targetKey] = form.lockHash;
+  }
   return lockEntries;
 }
+function carryGeneratedLock(lockEntries, baseline, key, sourceBaseKeys) {
+  if (!isGeneratedPluralKey(key, sourceBaseKeys)) {
+    return;
+  }
+  const prior = baseline.get(key);
+  if (prior !== void 0) {
+    lockEntries[key] = prior;
+  }
+}
 
 // src/flow/source.ts
 async function readSource(config, cwd, fs, adapter) {
@@ -1702,6 +2177,9 @@ async function translate2(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const dryRun = input.dryRun ?? false;
+  const prune = input.prune ?? config.prune ?? false;
+  const generatePlurals = input.generatePlurals ?? config.generatePlurals ?? false;
+  const maxBatchSize = config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
   const fs = deps.fs ?? defaultFs;
   const adapter = selectAdapter(config.format, deps.adapterRegistry);
   const provider = dryRun ? void 0 : selectProvider(config.provider, deps.createProvider);
@@ -1724,6 +2202,9 @@ async function translate2(input, deps = {}) {
         format: config.format,
         glossary: config.glossary,
         tone: config.tone,
+        prune,
+        generatePlurals,
+        maxBatchSize,
         fs
       };
       const { summary, lockEntries } = await runLocale(params);
@@ -2194,8 +2675,12 @@ function importLocale(params) {
     translated: [...buckets.accepted.keys()].sort(),
     unchanged: diff.unchanged,
     orphaned: diff.orphaned,
+    // Import never prunes: orphans are reported but never removed here (pruning is a translate-flow concern).
+    pruned: [],
     invalidIcuSource,
     integrityMismatches: [...buckets.mismatches].sort(),
+    // Plural generation is a translate-flow concern; the manual workbook import never generates forms.
+    generated: [],
     notices: []
   };
   return { summary, accepted: buckets.accepted, withheld: buckets.withheld };