@verbatra/sdk 0.2.2 → 0.4.0

package/dist/index.js

@@ -5,11 +5,15 @@ import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
 import * as deepl from 'deepl-node';
+import { createRequire } from 'module';
 import log from 'loglevel';
 import { GoogleGenAI } from '@google/genai';
 import OpenAI from 'openai';
+import { randomUUID } from 'crypto';
 import { access, writeFile, rename, rm, open } from 'fs/promises';
-import { parse, TYPE } from '@formatjs/icu-messageformat-parser';
+import { parse as parse$1, TYPE } from '@formatjs/icu-messageformat-parser';
+import { XMLSerializer, DOMParser } from '@xmldom/xmldom';
+import { stringify, parse } from 'yaml';
 import ExcelJS from 'exceljs';
 import JSZip from 'jszip';
 import { watch as watch$1 } from 'chokidar';
@@ -44,13 +48,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) {
@@ -96,7 +103,10 @@ var SUPPORTED_FORMATS = [
   "i18next-json",
   "vue-i18n-json",
   "next-intl-json",
-  "ngx-translate-json"
+  "ngx-translate-json",
+  "xliff",
+  "yaml",
+  "arb"
 ];
 var supportedFormatSchema = z.enum(SUPPORTED_FORMATS);
 var translationEntrySchema = z.object({
@@ -114,17 +124,31 @@ z.object({
   format: supportedFormatSchema,
   entries: z.map(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,
@@ -137,6 +161,26 @@ var LOCALE_TOKEN = "{locale}";
 function localeFilePath(cwd, pattern, locale) {
   return resolve(cwd, pattern.replaceAll(LOCALE_TOKEN, locale));
 }
+var REDACTED = "[REDACTED]";
+var KEY_PATTERNS = [
+  // The `\b` anchors `sk-` to a word start so hyphenated words like "risk-" or "task-" pass through.
+  /\bsk-[A-Za-z0-9_-]{8,}/g,
+  /AIza[0-9A-Za-z_-]{35}/g,
+  /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(?::fx)?/g
+];
+function escapeForRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function redact(text, secret = process.env.ANTHROPIC_API_KEY) {
+  let out = text;
+  for (const pattern of KEY_PATTERNS) {
+    out = out.replace(pattern, REDACTED);
+  }
+  if (secret !== void 0 && secret.length > 0) {
+    out = out.replace(new RegExp(escapeForRegExp(secret), "g"), REDACTED);
+  }
+  return out;
+}
 var ProviderError = class extends Error {
   /** The stable {@link ProviderErrorCode} for this failure; branch on this, not the message. */
   code;
@@ -145,7 +189,7 @@ var ProviderError = class extends Error {
    * @param message - A fixed, safe message; callers must never pass key, SDK, or request-derived text.
    */
   constructor(code, message) {
-    super(message);
+    super(redact(message, ""));
     this.name = "ProviderError";
     this.code = code;
   }
@@ -266,6 +310,18 @@ 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);
+  }
+}
+var PROVIDER_ENV = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  gemini: "GEMINI_API_KEY",
+  deepl: "DEEPL_API_KEY"
+};
 function readRequiredEnv(name) {
   const value = process.env[name];
   if (value === void 0 || value.length === 0) {
@@ -274,16 +330,16 @@ function readRequiredEnv(name) {
   return value;
 }
 function requireAnthropicKey() {
-  return readRequiredEnv("ANTHROPIC_API_KEY");
+  return readRequiredEnv(PROVIDER_ENV.anthropic);
 }
 function requireOpenAiKey() {
-  return readRequiredEnv("OPENAI_API_KEY");
+  return readRequiredEnv(PROVIDER_ENV.openai);
 }
 function requireGeminiKey() {
-  return readRequiredEnv("GEMINI_API_KEY");
+  return readRequiredEnv(PROVIDER_ENV.gemini);
 }
 function requireDeepLKey() {
-  return readRequiredEnv("DEEPL_API_KEY");
+  return readRequiredEnv(PROVIDER_ENV.deepl);
 }
 function createDefaultClient() {
   const sdk = new Anthropic({ apiKey: requireAnthropicKey(), logLevel: "off" });
@@ -361,6 +417,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 };
@@ -383,8 +440,22 @@ function toUsage(usage) {
 var deepLConfigSchema = z.object({
   glossaryId: z.string().min(1).optional()
 });
+var DEEPL_LOGGER = "deepl";
+function resolveDeeplLoglevel(requireFn = createRequire(import.meta.url)) {
+  try {
+    const entry = requireFn.resolve("deepl-node");
+    return createRequire(entry)("loglevel");
+  } catch {
+    return void 0;
+  }
+}
+function silenceDeeplLogger(instances) {
+  for (const instance of instances) {
+    instance?.getLogger(DEEPL_LOGGER).setLevel("silent");
+  }
+}
 function silenceSdkLogging() {
-  log.getLogger("deepl").setLevel("silent");
+  silenceDeeplLogger([log, resolveDeeplLoglevel()]);
 }
 function createDefaultClient2() {
   silenceSdkLogging();
@@ -608,6 +679,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.");
@@ -704,10 +776,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.");
   }
@@ -742,6 +816,11 @@ function createMechanism3(client, config) {
 function callClient4(client, body) {
   return guardProviderCall(() => client.chat.completions.create(body));
 }
+var SCAFFOLD_MODELS = {
+  anthropic: "claude-sonnet-4-6",
+  openai: "gpt-5.4-mini",
+  gemini: "gemini-2.5-flash"
+};
 var providerConfigSchema = z.discriminatedUnion("id", [
   z.object({ id: z.literal("anthropic"), options: anthropicConfigSchema.strict() }),
   z.object({ id: z.literal("openai"), options: openAiConfigSchema.strict() }),
@@ -760,6 +839,7 @@ function buildProvider(config) {
 }
 
 // src/config/schema.ts
+var DEFAULT_MAX_BATCH_SIZE = 50;
 var verbatraConfigSchema = z.strictObject({
   sourceLocale: z.string().min(1),
   targetLocales: z.array(z.string().min(1)).min(1),
@@ -769,7 +849,29 @@ var verbatraConfigSchema = z.strictObject({
   }),
   provider: providerConfigSchema,
   glossary: z.record(z.string(), z.string()).optional(),
-  tone: z.enum(["formal", "informal", "neutral"]).optional()
+  tone: z.enum(["formal", "informal", "neutral"]).optional(),
+  /**
+   * Opt-in orphan pruning, off by default. When true, keys present in a target file but absent from
+   * the source are removed from the written file and the lock. The per-run `prune` option on
+   * `translate` (the CLI `--prune` flag) overrides this.
+   */
+  prune: z.boolean().optional(),
+  /**
+   * Opt-in plural-category generation, off by default. 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). The 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: z.boolean().optional(),
+  /**
+   * Optional maximum number of entries sent in a single provider request. A locale's missing and
+   * 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 while the others make progress. Must
+   * be a positive integer (zero, negative, or non-integer is rejected, never coerced). When absent,
+   * {@link DEFAULT_MAX_BATCH_SIZE} applies.
+   */
+  maxBatchSize: z.number().int().positive().optional()
 }).refine((config) => !config.targetLocales.includes(config.sourceLocale), {
   message: "targetLocales must not include the source locale",
   path: ["targetLocales"]
@@ -914,8 +1016,11 @@ async function readBoundedBytes(path, maxBytes) {
     await handle.close();
   }
 }
+function tempFileName(path) {
+  return join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`);
+}
 async function atomicWrite(path, data) {
-  const tmp = join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${Date.now()}`);
+  const tmp = tempFileName(path);
   await (typeof data === "string" ? writeFile(tmp, data, "utf8") : writeFile(tmp, data));
   try {
     await rename(tmp, path);
@@ -996,6 +1101,85 @@ async function writeLockFile(path, lock, fs) {
   await fs.writeFile(path, `${JSON.stringify(ordered, null, 2)}
 `);
 }
+var VALID_EMPTY = { placeholders: [], isPlural: false, valid: true };
+var INVALID = { placeholders: [], isPlural: false, valid: false };
+function tokenOf(element) {
+  switch (element.type) {
+    case TYPE.argument:
+    case TYPE.number:
+    case TYPE.date:
+    case TYPE.time:
+    case TYPE.select:
+    case TYPE.plural:
+      return `{${element.value}}`;
+    case TYPE.tag:
+      return `<${element.value}>`;
+    default:
+      return void 0;
+  }
+}
+function childMessages(element) {
+  if (element.type === TYPE.plural || element.type === TYPE.select) {
+    return Object.values(element.options).map((option) => option.value);
+  }
+  if (element.type === TYPE.tag) {
+    return [element.children];
+  }
+  return [];
+}
+function collect(elements, add, state) {
+  for (const element of elements) {
+    const token = tokenOf(element);
+    if (token !== void 0) {
+      add(token);
+    }
+    if (element.type === TYPE.plural) {
+      state.isPlural = true;
+    }
+    for (const child of childMessages(element)) {
+      collect(child, add, state);
+    }
+  }
+}
+function analyzeIcuValue(value) {
+  if (!value.includes("{") && !value.includes("<")) {
+    return VALID_EMPTY;
+  }
+  try {
+    const ast = parse$1(value);
+    const placeholders = [];
+    const state = { isPlural: false };
+    collect(
+      ast,
+      (token) => {
+        placeholders.push(token);
+      },
+      state
+    );
+    return { placeholders, isPlural: state.isPlural, valid: true };
+  } catch {
+    return INVALID;
+  }
+}
+function icuPlaceholders(value) {
+  return analyzeIcuValue(value).placeholders;
+}
+function icuIsValid(value) {
+  return analyzeIcuValue(value).valid;
+}
+function icuDeriveEntry(_key, value) {
+  const analysis = analyzeIcuValue(value);
+  return { placeholders: analysis.placeholders, isPlural: analysis.isPlural };
+}
+function icuInvalidKeys(entries) {
+  const invalid = [];
+  for (const [key, entry] of entries) {
+    if (!icuIsValid(entry.value)) {
+      invalid.push(key);
+    }
+  }
+  return invalid;
+}
 var AdapterError = class extends Error {
   code;
   constructor(code, message) {
@@ -1004,6 +1188,82 @@ var AdapterError = class extends Error {
     this.code = code;
   }
 };
+var MAX_DEPTH = 100;
+var MAX_INPUT_BYTES = 16 * 1024 * 1024;
+var jsonTreeSchema = z.lazy(
+  () => z.union([z.string(), z.record(z.string(), jsonTreeSchema)])
+);
+var rootSchema = z.record(z.string(), jsonTreeSchema);
+function assertWithinDepth(value, max) {
+  const stack = [{ node: value, depth: 1 }];
+  while (stack.length > 0) {
+    const top = stack.pop();
+    if (top === void 0) {
+      break;
+    }
+    const { node, depth } = top;
+    if (typeof node !== "object" || node === null) {
+      continue;
+    }
+    if (depth > max) {
+      throw new AdapterError("MAX_DEPTH_EXCEEDED", "The file nests objects too deeply.");
+    }
+    for (const child of Object.values(node)) {
+      stack.push({ node: child, depth: depth + 1 });
+    }
+  }
+}
+function assertJsonRecord(value) {
+  assertWithinDepth(value, MAX_DEPTH);
+  const result = rootSchema.safeParse(value);
+  if (!result.success) {
+    throw new AdapterError(
+      "INVALID_STRUCTURE",
+      "The file is not a valid object (expected nested objects of string values)."
+    );
+  }
+  return result.data;
+}
+function parseJsonObject(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new AdapterError("INVALID_JSON", "The file is not valid JSON.");
+  }
+  return assertJsonRecord(parsed);
+}
+function serializeJsonTree(tree) {
+  return `${JSON.stringify(tree, null, 2)}
+`;
+}
+function namespaceOf(filePath) {
+  return basename(filePath, extname(filePath));
+}
+function rethrowStructured(error, message) {
+  if (error instanceof AdapterError) {
+    throw error;
+  }
+  throw new AdapterError("INVALID_STRUCTURE", message);
+}
+function computeIcu(entries, compute) {
+  if (!compute) {
+    return [];
+  }
+  try {
+    return compute(entries);
+  } catch (error) {
+    rethrowStructured(error, "The file could not be analyzed for message validity.");
+  }
+}
+function buildCanHandle(extensions, sniff) {
+  return (filePath, sample) => {
+    if (!extensions.includes(extname(filePath).toLowerCase())) {
+      return false;
+    }
+    return sample === void 0 || sniff === void 0 || sniff(sample);
+  };
+}
 var nodeOps = {
   writeFile: (path, data) => writeFile(path, data, "utf8"),
   rename: (from, to) => rename(from, to),
@@ -1015,8 +1275,11 @@ async function cleanup(ops, tmp) {
   } catch {
   }
 }
+function tempFileName2(path) {
+  return join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`);
+}
 async function atomicWriteFile(path, data, ops = nodeOps) {
-  const tmp = join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${Date.now()}`);
+  const tmp = tempFileName2(path);
   try {
     await ops.writeFile(tmp, data);
     await ops.rename(tmp, path);
@@ -1025,8 +1288,6 @@ async function atomicWriteFile(path, data, ops = nodeOps) {
     throw error;
   }
 }
-var MAX_DEPTH = 100;
-var MAX_INPUT_BYTES = 16 * 1024 * 1024;
 async function readBoundedUtf82(handle, size) {
   const buffer = Buffer.allocUnsafe(size);
   let offset = 0;
@@ -1054,61 +1315,128 @@ async function readBounded2(filePath) {
     await handle.close();
   }
 }
-function addEntries(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 });
+async function readFileContent(filePath) {
+  const outcome = await readBounded2(filePath);
+  if (outcome.kind === "not-a-file") {
+    throw new AdapterError("INVALID_STRUCTURE", "The path is not a regular file.");
+  }
+  if (outcome.kind === "too-large") {
+    throw new AdapterError("INPUT_TOO_LARGE", "The file exceeds the maximum allowed size.");
+  }
+  return outcome.content;
+}
+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 {
-      addEntries(value, path, namespace, derive, out);
+      out += char;
     }
   }
-}
-function flattenTree(tree, namespace, derive) {
-  const out = /* @__PURE__ */ new Map();
-  addEntries(tree, "", namespace, derive, out);
   return out;
 }
-var jsonTreeSchema = z.lazy(
-  () => z.union([z.string(), z.record(z.string(), jsonTreeSchema)])
-);
-var rootSchema = z.record(z.string(), jsonTreeSchema);
-function assertWithinDepth(value, max) {
-  const stack = [{ node: value, depth: 1 }];
-  while (stack.length > 0) {
-    const top = stack.pop();
-    if (top === void 0) {
-      break;
-    }
-    const { node, depth } = top;
-    if (typeof node !== "object" || node === null) {
-      continue;
-    }
-    if (depth > max) {
-      throw new AdapterError("MAX_DEPTH_EXCEEDED", "The file nests objects too deeply.");
-    }
-    for (const child of Object.values(node)) {
-      stack.push({ node: child, depth: depth + 1 });
+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 parseJsonObject(content) {
-  let parsed;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    throw new AdapterError("INVALID_JSON", "The file is not valid JSON.");
+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;
+    }
   }
-  assertWithinDepth(parsed, MAX_DEPTH);
-  const result = rootSchema.safeParse(parsed);
-  if (!result.success) {
+  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",
-      "The file is not a valid JSON object (expected nested objects of string values)."
+      "A literal dotted leaf key and a nested key path resolve to the same path."
     );
   }
-  return result.data;
+  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 {
+      addPathEntries(value, path, namespace, derive, out);
+    }
+  }
+}
+function flattenTree(tree, namespace, derive, keyMode = "literal-leaf") {
+  const out = /* @__PURE__ */ new Map();
+  if (keyMode === "path-notation") {
+    addPathEntries(tree, "", namespace, derive, out);
+    return out;
+  }
+  addEntries({ namespace, derive, out, claimed: /* @__PURE__ */ new Map() }, [], tree);
+  return out;
 }
 function emptyNode() {
   return /* @__PURE__ */ Object.create(null);
@@ -1134,103 +1462,194 @@ 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;
 }
-function namespaceOf(filePath) {
-  return basename(filePath, extname(filePath));
-}
-function canHandle(filePath, sample) {
-  if (extname(filePath).toLowerCase() !== ".json") {
-    return false;
-  }
-  return sample === void 0 || sample.trimStart().startsWith("{");
-}
-function rethrowStructured(error, message) {
-  if (error instanceof AdapterError) {
-    throw error;
-  }
-  throw new AdapterError("INVALID_STRUCTURE", message);
-}
-function toEntries(content, namespace, deriveEntry, validateTree) {
+function toEntries(content, namespace, parse2, deriveEntry, keyMode, validateTree) {
   try {
-    const tree = parseJsonObject(content);
+    const tree = parse2(content);
     validateTree?.(tree);
-    return flattenTree(tree, namespace, deriveEntry);
-  } catch (error) {
-    rethrowStructured(error, "The file could not be read as JSON.");
-  }
-}
-function computeIcu(entries, compute) {
-  if (!compute) {
-    return [];
-  }
-  try {
-    return compute(entries);
+    return flattenTree(tree, namespace, deriveEntry, keyMode);
   } catch (error) {
-    rethrowStructured(error, "The file could not be analyzed for message validity.");
+    rethrowStructured(error, "The file could not be parsed.");
   }
 }
-function createJsonFileAdapter(options) {
+function createTreeFileAdapter(options) {
   const {
     format,
+    extensions,
+    sniff,
+    parse: parse2,
+    serialize,
     deriveEntry,
-    extractPlaceholders: extractPlaceholders2,
-    computeInvalidIcuKeys: computeInvalidIcuKeys2,
-    validateMessage: validateMessage2,
+    extractPlaceholders,
+    computeInvalidIcuKeys,
+    validateMessage,
     validateTree,
-    buildWriteTree
+    buildWriteTree,
+    keyMode = "literal-leaf"
   } = options;
   return {
     format,
-    canHandle,
-    extractPlaceholders: extractPlaceholders2,
-    // Non-ICU formats supply no validator: every value is valid for their syntax.
-    validateMessage: validateMessage2 ?? (() => true),
+    canHandle: buildCanHandle(extensions, sniff),
+    extractPlaceholders,
+    validateMessage: validateMessage ?? (() => true),
     async read(filePath, locale) {
-      const outcome = await readBounded2(filePath);
-      if (outcome.kind === "not-a-file") {
-        throw new AdapterError("INVALID_STRUCTURE", "The path is not a regular file.");
-      }
-      if (outcome.kind === "too-large") {
-        throw new AdapterError("INPUT_TOO_LARGE", "The file exceeds the maximum allowed size.");
-      }
+      const content = await readFileContent(filePath);
       const namespace = namespaceOf(filePath);
-      const entries = toEntries(outcome.content, namespace, deriveEntry, validateTree);
+      const entries = toEntries(content, namespace, parse2, deriveEntry, keyMode, validateTree);
       const resource = { locale, namespace, format, entries };
-      const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys2);
+      const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys);
       return { resource, invalidIcuKeys };
     },
     async write(resource, filePath) {
       const tree = buildWriteTree ? await buildWriteTree(resource.entries, filePath) : unflattenEntries(resource.entries);
-      await atomicWriteFile(filePath, `${JSON.stringify(tree, null, 2)}
-`);
+      await atomicWriteFile(filePath, serialize(tree));
     }
   };
 }
-var PLACEHOLDER_PATTERN = /\{\{[^{}]*\}\}/g;
-function extractI18nextPlaceholders(value) {
-  const seen = /* @__PURE__ */ new Set();
+function isMetadataKey(key) {
+  return key.startsWith("@");
+}
+function parseArbObject(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new AdapterError("INVALID_JSON", "The file is not valid JSON.");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new AdapterError(
+      "INVALID_STRUCTURE",
+      "The file is not a valid object (expected nested objects of string values)."
+    );
+  }
+  return parsed;
+}
+function stripArbMetadata(tree) {
+  const out = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of Object.entries(tree)) {
+    if (!isMetadataKey(key)) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function originalKey(encoded) {
+  return decodeKeyToSegments(encoded).join(".");
+}
+function messagesFromEntries(entries) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, entry] of entries) {
+    out.set(originalKey(key), entry.value);
+  }
+  return out;
+}
+async function readDestinationPairs(filePath) {
+  let parsed;
+  try {
+    const outcome = await readBounded2(filePath);
+    if (outcome.kind !== "ok") {
+      return null;
+    }
+    parsed = JSON.parse(outcome.content);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+  return Object.entries(parsed);
+}
+async function buildArbWriteTree(entries, filePath) {
+  const messages = messagesFromEntries(entries);
+  const pairs = await readDestinationPairs(filePath);
+  const out = /* @__PURE__ */ Object.create(null);
+  const consumed = /* @__PURE__ */ new Set();
+  for (const [key, value] of pairs ?? []) {
+    const translated = isMetadataKey(key) ? void 0 : messages.get(key);
+    if (translated !== void 0) {
+      consumed.add(key);
+    }
+    out[key] = translated ?? value;
+  }
+  for (const [key, value] of messages) {
+    if (!consumed.has(key)) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function parseArb(content) {
+  return assertJsonRecord(stripArbMetadata(parseArbObject(content)));
+}
+function createArbAdapter() {
+  return createTreeFileAdapter({
+    format: "arb",
+    extensions: [".arb"],
+    sniff: (sample) => sample.trimStart().startsWith("{"),
+    parse: parseArb,
+    serialize: serializeJsonTree,
+    extractPlaceholders: icuPlaceholders,
+    deriveEntry: icuDeriveEntry,
+    computeInvalidIcuKeys: icuInvalidKeys,
+    validateMessage: icuIsValid,
+    buildWriteTree: buildArbWriteTree
+  });
+}
+function createJsonFileAdapter(options) {
+  return createTreeFileAdapter({
+    ...options,
+    extensions: [".json"],
+    sniff: (sample) => sample.trimStart().startsWith("{"),
+    parse: parseJsonObject,
+    serialize: serializeJsonTree
+  });
+}
+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",
@@ -1241,95 +1660,13 @@ function createI18nextJsonAdapter() {
     })
   });
 }
-var VALID_EMPTY = { placeholders: [], isPlural: false, valid: true };
-var INVALID = { placeholders: [], isPlural: false, valid: false };
-function tokenOf(element) {
-  switch (element.type) {
-    case TYPE.argument:
-    case TYPE.number:
-    case TYPE.date:
-    case TYPE.time:
-    case TYPE.select:
-    case TYPE.plural:
-      return `{${element.value}}`;
-    case TYPE.tag:
-      return `<${element.value}>`;
-    default:
-      return void 0;
-  }
-}
-function childMessages(element) {
-  if (element.type === TYPE.plural || element.type === TYPE.select) {
-    return Object.values(element.options).map((option) => option.value);
-  }
-  if (element.type === TYPE.tag) {
-    return [element.children];
-  }
-  return [];
-}
-function collect(elements, add, state) {
-  for (const element of elements) {
-    const token = tokenOf(element);
-    if (token !== void 0) {
-      add(token);
-    }
-    if (element.type === TYPE.plural) {
-      state.isPlural = true;
-    }
-    for (const child of childMessages(element)) {
-      collect(child, add, state);
-    }
-  }
-}
-function analyzeIcuValue(value) {
-  if (!value.includes("{") && !value.includes("<")) {
-    return VALID_EMPTY;
-  }
-  try {
-    const ast = 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);
-        }
-      },
-      state
-    );
-    return { placeholders, isPlural: state.isPlural, valid: true };
-  } catch {
-    return INVALID;
-  }
-}
-function extractPlaceholders(value) {
-  return analyzeIcuValue(value).placeholders;
-}
-function validateMessage(value) {
-  return analyzeIcuValue(value).valid;
-}
-function computeInvalidIcuKeys(entries) {
-  const invalid = [];
-  for (const [key, entry] of entries) {
-    if (!validateMessage(entry.value)) {
-      invalid.push(key);
-    }
-  }
-  return invalid;
-}
 function createNextIntlJsonAdapter() {
   return createJsonFileAdapter({
     format: "next-intl-json",
-    extractPlaceholders,
-    deriveEntry: (_key, value) => {
-      const analysis = analyzeIcuValue(value);
-      return { placeholders: analysis.placeholders, isPlural: analysis.isPlural };
-    },
-    computeInvalidIcuKeys,
-    validateMessage
+    extractPlaceholders: icuPlaceholders,
+    deriveEntry: icuDeriveEntry,
+    computeInvalidIcuKeys: icuInvalidKeys,
+    validateMessage: icuIsValid
   });
 }
 function assertNotMixed(tree) {
@@ -1384,13 +1721,15 @@ 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.
+    keyMode: "path-notation"
   });
 }
 var AdapterRegistry = class {
@@ -1441,15 +1780,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;
@@ -1467,8 +1804,245 @@ function createVueI18nJsonAdapter() {
     })
   });
 }
+function toEntries2(content, namespace, parseEntries) {
+  try {
+    return parseEntries(content, namespace);
+  } catch (error) {
+    rethrowStructured(error, "The file could not be parsed.");
+  }
+}
+function createFlatFileAdapter(options) {
+  const {
+    format,
+    extensions,
+    sniff,
+    parseEntries,
+    serializeEntries,
+    extractPlaceholders,
+    validateMessage,
+    computeInvalidIcuKeys
+  } = options;
+  return {
+    format,
+    canHandle: buildCanHandle(extensions, sniff),
+    extractPlaceholders,
+    validateMessage: validateMessage ?? (() => true),
+    async read(filePath, locale) {
+      const content = await readFileContent(filePath);
+      const namespace = namespaceOf(filePath);
+      const entries = toEntries2(content, namespace, parseEntries);
+      const resource = { locale, namespace, format, entries };
+      const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys);
+      return { resource, invalidIcuKeys };
+    },
+    async write(resource, filePath) {
+      const data = await serializeEntries(resource.entries, filePath);
+      await atomicWriteFile(filePath, data);
+    }
+  };
+}
+var XLIFF_PATTERN = /<(?:x|g|bx|ex|ph|it|mrk)\b[^>]*>|\{[^{}]+\}/g;
+function extractXliffPlaceholders(value) {
+  const result = [];
+  for (const match of value.matchAll(XLIFF_PATTERN)) {
+    const token = match[0];
+    if (token !== void 0) {
+      result.push(token);
+    }
+  }
+  return result;
+}
+var ELEMENT_NODE = 1;
+function isElement(node) {
+  return node.nodeType === ELEMENT_NODE;
+}
+function elementChildren(parent) {
+  return Array.from(parent.childNodes).filter(isElement);
+}
+function childByName(parent, name) {
+  return elementChildren(parent).find((el) => el.localName === name) ?? null;
+}
+function collectByTag(root, name) {
+  return Array.from(root.getElementsByTagName(name));
+}
+function unitKey(element, index) {
+  return element.getAttribute("id") ?? element.getAttribute("resname") ?? `unit-${index}`;
+}
+function onFatal(level) {
+  if (level === "fatalError") {
+    throw new Error("malformed XML");
+  }
+}
+function assertNoDoctype(content) {
+  if (/<!DOCTYPE/i.test(content) || /<!ENTITY/i.test(content)) {
+    throw new AdapterError("INVALID_XML", "XLIFF with a DTD or entity declaration is rejected.");
+  }
+}
+function parseXml(content) {
+  assertNoDoctype(content);
+  let doc;
+  try {
+    doc = new DOMParser({ onError: onFatal }).parseFromString(content, "text/xml");
+  } catch {
+    throw new AdapterError("INVALID_XML", "The file is not valid XML.");
+  }
+  const root = doc.documentElement;
+  if (root === null || root.localName !== "xliff") {
+    throw new AdapterError("INVALID_STRUCTURE", "The file is not an XLIFF document.");
+  }
+  return { doc, root };
+}
+function walkXliff12(root) {
+  const units = [];
+  collectByTag(root, "trans-unit").forEach((tu, index) => {
+    const source = childByName(tu, "source");
+    if (source !== null) {
+      units.push({
+        key: unitKey(tu, index),
+        source,
+        target: childByName(tu, "target"),
+        container: tu
+      });
+    }
+  });
+  return units;
+}
+function walkXliff20(root) {
+  const units = [];
+  collectByTag(root, "unit").forEach((unit, index) => {
+    const baseKey = unitKey(unit, index);
+    const segments = elementChildren(unit).filter((el) => el.localName === "segment");
+    segments.forEach((segment, segIndex) => {
+      const source = childByName(segment, "source");
+      if (source !== null) {
+        const key = segments.length > 1 ? `${baseKey}#${segIndex}` : baseKey;
+        units.push({ key, source, target: childByName(segment, "target"), container: segment });
+      }
+    });
+  });
+  return units;
+}
+function walkUnits(root) {
+  const version = root.getAttribute("version") ?? "1.2";
+  return version.startsWith("2") ? walkXliff20(root) : walkXliff12(root);
+}
+function innerXml(serializer, element) {
+  return Array.from(element.childNodes).map((node) => serializer.serializeToString(node)).join("");
+}
+function unitValue(serializer, unit) {
+  if (unit.target !== null) {
+    const targetXml = innerXml(serializer, unit.target);
+    if (targetXml.trim() !== "") {
+      return targetXml;
+    }
+  }
+  return innerXml(serializer, unit.source);
+}
+function parseXliffEntries(content, namespace) {
+  const { root } = parseXml(content);
+  const serializer = new XMLSerializer();
+  const out = /* @__PURE__ */ new Map();
+  for (const unit of walkUnits(root)) {
+    const value = unitValue(serializer, unit);
+    out.set(unit.key, {
+      key: unit.key,
+      namespace,
+      value,
+      placeholders: extractXliffPlaceholders(value),
+      isPlural: false
+    });
+  }
+  return out;
+}
+async function readDestination(filePath) {
+  let outcome;
+  try {
+    outcome = await readBounded2(filePath);
+  } catch {
+    throw new AdapterError("INVALID_STRUCTURE", "The destination XLIFF file does not exist.");
+  }
+  if (outcome.kind === "not-a-file") {
+    throw new AdapterError("INVALID_STRUCTURE", "The destination path is not a regular file.");
+  }
+  if (outcome.kind === "too-large") {
+    throw new AdapterError("INPUT_TOO_LARGE", "The file exceeds the maximum allowed size.");
+  }
+  return outcome.content;
+}
+function fragmentNodes(parser, value) {
+  try {
+    const root = parser.parseFromString(`<wrapper>${value}</wrapper>`, "text/xml").documentElement;
+    return root === null ? null : Array.from(root.childNodes);
+  } catch {
+    return null;
+  }
+}
+function setTargetValue(doc, parser, element, value) {
+  while (element.firstChild !== null) {
+    element.removeChild(element.firstChild);
+  }
+  const nodes = fragmentNodes(parser, value);
+  if (nodes === null) {
+    element.textContent = value;
+    return;
+  }
+  for (const node of nodes) {
+    element.appendChild(doc.importNode(node, true));
+  }
+}
+async function serializeXliffEntries(entries, filePath) {
+  const { doc, root } = parseXml(await readDestination(filePath));
+  const parser = new DOMParser({ onError: onFatal });
+  for (const unit of walkUnits(root)) {
+    const entry = entries.get(unit.key);
+    if (entry !== void 0) {
+      const target = unit.target ?? doc.createElement("target");
+      if (unit.target === null) {
+        unit.container.appendChild(target);
+      }
+      setTargetValue(doc, parser, target, entry.value);
+    }
+  }
+  return new XMLSerializer().serializeToString(doc);
+}
+function sniffXliff(sample) {
+  const head = sample.trimStart();
+  return head.startsWith("<xliff") || head.startsWith("<?xml");
+}
+function createXliffAdapter() {
+  return createFlatFileAdapter({
+    format: "xliff",
+    extensions: [".xlf", ".xliff"],
+    sniff: sniffXliff,
+    parseEntries: parseXliffEntries,
+    serializeEntries: serializeXliffEntries,
+    extractPlaceholders: extractXliffPlaceholders
+  });
+}
+function parseYamlObject(content) {
+  let parsed;
+  try {
+    parsed = parse(content, { maxAliasCount: 100 });
+  } catch {
+    throw new AdapterError("INVALID_YAML", "The file is not valid YAML.");
+  }
+  return assertJsonRecord(parsed);
+}
+function createYamlAdapter() {
+  return createTreeFileAdapter({
+    format: "yaml",
+    extensions: [".yml", ".yaml"],
+    parse: parseYamlObject,
+    serialize: (tree) => stringify(tree),
+    extractPlaceholders: extractDoubleBracePlaceholders,
+    deriveEntry: (_key, value) => ({
+      placeholders: extractDoubleBracePlaceholders(value),
+      isPlural: false
+    })
+  });
+}
 function createDefaultRegistry() {
-  return new AdapterRegistry().register(createI18nextJsonAdapter()).register(createVueI18nJsonAdapter()).register(createNextIntlJsonAdapter()).register(createNgxTranslateJsonAdapter());
+  return new AdapterRegistry().register(createI18nextJsonAdapter()).register(createVueI18nJsonAdapter()).register(createNextIntlJsonAdapter()).register(createNgxTranslateJsonAdapter()).register(createXliffAdapter()).register(createYamlAdapter()).register(createArbAdapter());
 }
 
 // src/selection/select-adapter.ts
@@ -1483,6 +2057,89 @@ function selectAdapter(format, registry = createDefaultRegistry()) {
   );
 }
 
+// src/flow/source.ts
+async function readSource(config, cwd, fs, adapter) {
+  const sourcePath = localeFilePath(cwd, config.files.pattern, config.sourceLocale);
+  if (!await fs.fileExists(sourcePath)) {
+    throw new SdkError(
+      "SOURCE_UNREADABLE",
+      `The source locale file was not found at ${sourcePath}.`
+    );
+  }
+  try {
+    return await adapter.read(sourcePath, config.sourceLocale);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new SdkError(
+      "SOURCE_INVALID",
+      `The source locale file at ${sourcePath} could not be read: ${detail}`
+    );
+  }
+}
+
+// src/flow/diff-locales.ts
+async function readTarget(cwd, config, adapter, fs, locale) {
+  const path = localeFilePath(cwd, config.files.pattern, locale);
+  if (!await fs.fileExists(path)) {
+    return { locale, namespace: "", format: config.format, entries: /* @__PURE__ */ new Map() };
+  }
+  return (await adapter.read(path, locale)).resource;
+}
+function selectedLocales(config, requested) {
+  if (requested === void 0) {
+    return config.targetLocales;
+  }
+  const wanted = new Set(requested);
+  return config.targetLocales.filter((locale) => wanted.has(locale));
+}
+async function diffLocales(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const source = await readSource(config, cwd, fs, adapter);
+  const lock = await readLockFile(lockFilePath(cwd), fs);
+  return Promise.all(
+    selectedLocales(config, input.locales).map(async (locale) => {
+      const target = await readTarget(cwd, config, adapter, fs, locale);
+      const diff2 = diffResources(source.resource, target, { baseline: baselineFor(lock, locale) });
+      return { locale, diff: diff2 };
+    })
+  );
+}
+
+// src/flow/check.ts
+function toCheckSummary(locale, diff2) {
+  return {
+    locale,
+    missing: diff2.missing.length,
+    stale: diff2.changed.length,
+    upToDate: diff2.unchanged.length,
+    inSync: diff2.missing.length === 0 && diff2.changed.length === 0
+  };
+}
+async function check(input, deps = {}) {
+  const results = await diffLocales(input, deps);
+  const locales = results.map(({ locale, diff: diff2 }) => toCheckSummary(locale, diff2));
+  return { inSync: locales.every((entry) => entry.inSync), locales };
+}
+
+// src/flow/diff.ts
+function toLocaleDiff(locale, diff2) {
+  return {
+    locale,
+    missing: diff2.missing,
+    changed: diff2.changed,
+    orphaned: diff2.orphaned,
+    hasPendingChanges: diff2.missing.length > 0 || diff2.changed.length > 0
+  };
+}
+async function diff(input, deps = {}) {
+  const results = await diffLocales(input, deps);
+  const locales = results.map(({ locale, diff: result }) => toLocaleDiff(locale, result));
+  return { hasPendingChanges: locales.some((entry) => entry.hasPendingChanges), locales };
+}
+
 // src/selection/select-provider.ts
 function selectProvider(config, createProvider = buildProvider) {
   try {
@@ -1511,8 +2168,10 @@ function failureSummary(locale, error) {
     translated: [],
     unchanged: [],
     orphaned: [],
+    pruned: [],
     invalidIcuSource: [],
     integrityMismatches: [],
+    generated: [],
     notices: [],
     error: describeError(error)
   };
@@ -1535,18 +2194,210 @@ 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() };
 }
-async function readTarget(params) {
+async function readTarget2(params) {
   const path = localeFilePath(params.cwd, params.filesPattern, params.targetLocale);
   if (!await params.fs.fileExists(path)) {
     return emptyResource(params.targetLocale, params.format);
   }
   return (await params.adapter.read(path, params.targetLocale)).resource;
 }
-function buildRequest2(params, entries) {
+function buildRequest3(params, entries) {
   return {
     sourceLocale: params.sourceLocale,
     targetLocale: params.targetLocale,
@@ -1557,27 +2408,58 @@ function buildRequest2(params, entries) {
   };
 }
 async function runLocale(params) {
-  const target = await readTarget(params);
-  const diff = diffResources(params.source, target, { baseline: params.baseline });
+  const target = await readTarget2(params);
+  const diff2 = diffResources(params.source, target, { baseline: params.baseline });
+  const orphaned = params.generatePlurals ? diff2.orphaned.filter((key) => !isGeneratedPluralKey(key, sourcePluralBaseKeys(params.source))) : diff2.orphaned;
+  const pruned = params.prune ? orphaned : [];
   const invalidIcu = new Set(params.sourceInvalidIcuKeys);
-  const candidates = [...diff.missing, ...diff.changed];
+  const candidates = [...diff2.missing, ...diff2.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: diff2.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(
     {
@@ -1588,37 +2470,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: diff2.unchanged,
+      orphaned,
       invalidIcuSource,
-      [...accepted.keys()],
-      integrityMismatches,
+      translated: [...accepted.keys()],
+      generated: generation.accepted.map((form) => form.targetKey).sort(),
+      // Withheld generated forms surface alongside withheld translations: 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) {
@@ -1629,11 +2557,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)) {
@@ -1645,26 +2590,18 @@ function computeLockEntries(params, merged, withheld) {
     }
     lockEntries[key] = contentHash(sourceEntry);
   }
+  for (const form of generated) {
+    lockEntries[form.targetKey] = form.lockHash;
+  }
   return lockEntries;
 }
-
-// src/flow/source.ts
-async function readSource(config, cwd, fs, adapter) {
-  const sourcePath = localeFilePath(cwd, config.files.pattern, config.sourceLocale);
-  if (!await fs.fileExists(sourcePath)) {
-    throw new SdkError(
-      "SOURCE_UNREADABLE",
-      `The source locale file was not found at ${sourcePath}.`
-    );
+function carryGeneratedLock(lockEntries, baseline, key, sourceBaseKeys) {
+  if (!isGeneratedPluralKey(key, sourceBaseKeys)) {
+    return;
   }
-  try {
-    return await adapter.read(sourcePath, config.sourceLocale);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new SdkError(
-      "SOURCE_INVALID",
-      `The source locale file at ${sourcePath} could not be read: ${detail}`
-    );
+  const prior = baseline.get(key);
+  if (prior !== void 0) {
+    lockEntries[key] = prior;
   }
 }
 
@@ -1673,6 +2610,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);
@@ -1695,6 +2635,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);
@@ -1870,7 +2813,7 @@ var DEFAULT_WORKBOOK_LIMITS = {
   maxRowsPerSheet: 1e5,
   maxCellsPerRow: 64
 };
-function assertNoDoctype(name, xml) {
+function assertNoDoctype2(name, xml) {
   if (/<!DOCTYPE/i.test(xml) || /<!ENTITY/i.test(xml)) {
     throw new ExchangeError(
       "WORKBOOK_INVALID",
@@ -1925,7 +2868,7 @@ async function guardWorkbookBytes(bytes, limits) {
         `The workbook decompresses to more than the maximum of ${limits.maxDecompressedBytes} bytes.`
       );
     }
-    assertNoDoctype(file.name, content);
+    assertNoDoctype2(file.name, content);
   }
 }
 var rowSchema = z.object({
@@ -2034,7 +2977,7 @@ async function readWorkbook(bytes, options = {}) {
 
 // src/flow/workbook/export-workbook.ts
 var DEFAULT_WORKBOOK_PATH = "verbatra-translations.xlsx";
-async function readTarget2(cwd, config, adapter, fs, locale) {
+async function readTarget3(cwd, config, adapter, fs, locale) {
   const path = localeFilePath(cwd, config.files.pattern, locale);
   if (!await fs.fileExists(path)) {
     return { locale, namespace: "", format: config.format, entries: /* @__PURE__ */ new Map() };
@@ -2042,7 +2985,7 @@ async function readTarget2(cwd, config, adapter, fs, locale) {
   return (await adapter.read(path, locale)).resource;
 }
 function buildRows(source, target, baseline, includeUnchanged) {
-  const diff = diffResources(source, target, { baseline });
+  const diff2 = diffResources(source, target, { baseline });
   const rows = [];
   const add = (keys, status) => {
     for (const key of keys) {
@@ -2060,14 +3003,14 @@ function buildRows(source, target, baseline, includeUnchanged) {
       });
     }
   };
-  add(diff.missing, "new");
-  add(diff.changed, "changed");
+  add(diff2.missing, "new");
+  add(diff2.changed, "changed");
   if (includeUnchanged) {
-    add(diff.unchanged, "changed");
+    add(diff2.unchanged, "changed");
   }
   return [...rows].sort((a, b) => a.key < b.key ? -1 : 1);
 }
-function selectedLocales(config, requested) {
+function selectedLocales2(config, requested) {
   if (requested === void 0) {
     return config.targetLocales;
   }
@@ -2081,10 +3024,10 @@ async function exportWorkbook(input, deps = {}) {
   const adapter = selectAdapter(config.format, deps.adapterRegistry);
   const source = await readSource(config, cwd, fs, adapter);
   const lock = await readLockFile(lockFilePath(cwd), fs);
-  const locales = selectedLocales(config, input.locales);
+  const locales = selectedLocales2(config, input.locales);
   const sheets = await Promise.all(
     locales.map(async (locale) => {
-      const target = await readTarget2(cwd, config, adapter, fs, locale);
+      const target = await readTarget3(cwd, config, adapter, fs, locale);
       const rows = buildRows(
         source.resource,
         target,
@@ -2154,7 +3097,7 @@ function classifyRows(params, buckets) {
   }
 }
 function importLocale(params) {
-  const diff = diffResources(params.source, params.target, { baseline: params.baseline });
+  const diff2 = diffResources(params.source, params.target, { baseline: params.baseline });
   const buckets = { accepted: /* @__PURE__ */ new Map(), mismatches: [], withheld: /* @__PURE__ */ new Set() };
   classifyRows(params, buckets);
   const rowKeys = new Set(params.sheet.rows.map((row) => row.key));
@@ -2163,10 +3106,14 @@ function importLocale(params) {
     locale: params.sheet.locale,
     status: "succeeded",
     translated: [...buckets.accepted.keys()].sort(),
-    unchanged: diff.unchanged,
-    orphaned: diff.orphaned,
+    unchanged: diff2.unchanged,
+    orphaned: diff2.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 };
@@ -2187,7 +3134,7 @@ async function readWorkbookBytes(path, fs) {
   }
   return read.bytes;
 }
-async function readTarget3(cwd, config, adapter, fs, locale) {
+async function readTarget4(cwd, config, adapter, fs, locale) {
   const path = localeFilePath(cwd, config.files.pattern, locale);
   if (!await fs.fileExists(path)) {
     return { locale, namespace: "", format: config.format, entries: /* @__PURE__ */ new Map() };
@@ -2226,7 +3173,7 @@ async function runSheet(ctx, sheet, lock) {
       `The workbook has a sheet for locale "${sheet.locale}", which is not a configured target locale.`
     );
   }
-  const target = await readTarget3(ctx.cwd, ctx.config, ctx.adapter, ctx.fs, sheet.locale);
+  const target = await readTarget4(ctx.cwd, ctx.config, ctx.adapter, ctx.fs, sheet.locale);
   const baseline = baselineFor(lock, sheet.locale);
   const { summary, accepted, withheld } = importLocale({
     sheet,
@@ -2296,6 +3243,16 @@ async function importWorkbook(input, deps = {}) {
   const { succeeded, failed } = partition(summaries);
   return { dryRun, locales: summaries, succeeded, failed };
 }
+
+// src/scaffolding.ts
+var scaffoldingMetadata = {
+  /** Provider id -> the environment variable its API key is read from. Owned by ai-providers. */
+  providerEnv: PROVIDER_ENV,
+  /** LLM provider id -> a cosmetic default scaffold model. Owned by ai-providers. DeepL has none. */
+  scaffoldModels: SCAFFOLD_MODELS,
+  /** The closed set of source format ids. Owned by core. */
+  supportedFormats: SUPPORTED_FORMATS
+};
 var defaultCreateWatcher = (paths) => {
   const fsWatcher = watch$1([...paths], { persistent: true, ignoreInitial: true });
   return {
@@ -2402,6 +3359,6 @@ async function watch(input, deps = {}) {
   return { stop };
 }
 
-export { DEFAULT_WORKBOOK_PATH, SdkError, defineConfig, exportWorkbook, importWorkbook, loadConfig, translate2 as translate, verbatraConfigSchema, watch };
+export { DEFAULT_WORKBOOK_PATH, SdkError, check, defineConfig, diff, exportWorkbook, importWorkbook, loadConfig, scaffoldingMetadata, translate2 as translate, verbatraConfigSchema, watch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map