@verbatra/sdk 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -7,16 +7,20 @@ var cosmiconfigTypescriptLoader = require('cosmiconfig-typescript-loader');
 var zod = require('zod');
 var Anthropic = require('@anthropic-ai/sdk');
 var deepl = require('deepl-node');
+var module$1 = require('module');
 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 xmldom = require('@xmldom/xmldom');
+var yaml = require('yaml');
 var ExcelJS = require('exceljs');
 var JSZip = require('jszip');
 var chokidar = require('chokidar');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 function _interopNamespace(e) {
@@ -129,7 +133,10 @@ var SUPPORTED_FORMATS = [
   "i18next-json",
   "vue-i18n-json",
   "next-intl-json",
-  "ngx-translate-json"
+  "ngx-translate-json",
+  "xliff",
+  "yaml",
+  "arb"
 ];
 var supportedFormatSchema = zod.z.enum(SUPPORTED_FORMATS);
 var translationEntrySchema = zod.z.object({
@@ -184,6 +191,26 @@ var LOCALE_TOKEN = "{locale}";
 function localeFilePath(cwd, pattern, locale) {
   return path.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;
@@ -192,7 +219,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;
   }
@@ -319,6 +346,12 @@ function assertNotTruncated(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) {
@@ -327,16 +360,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__default.default({ apiKey: requireAnthropicKey(), logLevel: "off" });
@@ -437,8 +470,22 @@ function toUsage(usage) {
 var deepLConfigSchema = zod.z.object({
   glossaryId: zod.z.string().min(1).optional()
 });
+var DEEPL_LOGGER = "deepl";
+function resolveDeeplLoglevel(requireFn = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
+  try {
+    const entry = requireFn.resolve("deepl-node");
+    return module$1.createRequire(entry)("loglevel");
+  } catch {
+    return void 0;
+  }
+}
+function silenceDeeplLogger(instances) {
+  for (const instance of instances) {
+    instance?.getLogger(DEEPL_LOGGER).setLevel("silent");
+  }
+}
 function silenceSdkLogging() {
-  log__default.default.getLogger("deepl").setLevel("silent");
+  silenceDeeplLogger([log__default.default, resolveDeeplLoglevel()]);
 }
 function createDefaultClient2() {
   silenceSdkLogging();
@@ -799,6 +846,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 = zod.z.discriminatedUnion("id", [
   zod.z.object({ id: zod.z.literal("anthropic"), options: anthropicConfigSchema.strict() }),
   zod.z.object({ id: zod.z.literal("openai"), options: openAiConfigSchema.strict() }),
@@ -829,27 +881,25 @@ var verbatraConfigSchema = zod.z.strictObject({
   glossary: zod.z.record(zod.z.string(), zod.z.string()).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.
+   * 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: 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
+   * 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: 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.
+   * 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: zod.z.number().int().positive().optional()
 }).refine((config) => !config.targetLocales.includes(config.sourceLocale), {
@@ -1081,6 +1131,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 icuMessageformatParser.TYPE.argument:
+    case icuMessageformatParser.TYPE.number:
+    case icuMessageformatParser.TYPE.date:
+    case icuMessageformatParser.TYPE.time:
+    case icuMessageformatParser.TYPE.select:
+    case icuMessageformatParser.TYPE.plural:
+      return `{${element.value}}`;
+    case icuMessageformatParser.TYPE.tag:
+      return `<${element.value}>`;
+    default:
+      return void 0;
+  }
+}
+function childMessages(element) {
+  if (element.type === icuMessageformatParser.TYPE.plural || element.type === icuMessageformatParser.TYPE.select) {
+    return Object.values(element.options).map((option) => option.value);
+  }
+  if (element.type === icuMessageformatParser.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 === icuMessageformatParser.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 = icuMessageformatParser.parse(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) {
@@ -1089,6 +1218,82 @@ var AdapterError = class extends Error {
     this.code = code;
   }
 };
+var MAX_DEPTH = 100;
+var MAX_INPUT_BYTES = 16 * 1024 * 1024;
+var jsonTreeSchema = zod.z.lazy(
+  () => zod.z.union([zod.z.string(), zod.z.record(zod.z.string(), jsonTreeSchema)])
+);
+var rootSchema = zod.z.record(zod.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 path.basename(filePath, path.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(path.extname(filePath).toLowerCase())) {
+      return false;
+    }
+    return sample === void 0 || sniff === void 0 || sniff(sample);
+  };
+}
 var nodeOps = {
   writeFile: (path, data) => promises.writeFile(path, data, "utf8"),
   rename: (from, to) => promises.rename(from, to),
@@ -1113,8 +1318,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;
@@ -1142,6 +1345,16 @@ async function readBounded2(filePath) {
     await handle.close();
   }
 }
+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 = "\\\\";
@@ -1255,46 +1468,6 @@ function flattenTree(tree, namespace, derive, keyMode = "literal-leaf") {
   addEntries({ namespace, derive, out, claimed: /* @__PURE__ */ new Map() }, [], tree);
   return out;
 }
-var jsonTreeSchema = zod.z.lazy(
-  () => zod.z.union([zod.z.string(), zod.z.record(zod.z.string(), jsonTreeSchema)])
-);
-var rootSchema = zod.z.record(zod.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 parseJsonObject(content) {
-  let parsed;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    throw new AdapterError("INVALID_JSON", "The file is not valid JSON.");
-  }
-  assertWithinDepth(parsed, MAX_DEPTH);
-  const result = rootSchema.safeParse(parsed);
-  if (!result.success) {
-    throw new AdapterError(
-      "INVALID_STRUCTURE",
-      "The file is not a valid JSON object (expected nested objects of string values)."
-    );
-  }
-  return result.data;
-}
 function emptyNode() {
   return /* @__PURE__ */ Object.create(null);
 }
@@ -1331,77 +1504,146 @@ function unflattenEntries(entries) {
   }
   return root;
 }
-function namespaceOf(filePath) {
-  return path.basename(filePath, path.extname(filePath));
-}
-function canHandle(filePath, sample) {
-  if (path.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, keyMode, 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, keyMode);
   } catch (error) {
-    rethrowStructured(error, "The file could not be read as JSON.");
+    rethrowStructured(error, "The file could not be parsed.");
   }
 }
-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 createJsonFileAdapter(options) {
+function createTreeFileAdapter(options) {
   const {
     format,
+    extensions,
+    sniff,
+    parse: parse2,
+    serialize,
     deriveEntry,
-    extractPlaceholders: extractPlaceholders2,
-    computeInvalidIcuKeys: computeInvalidIcuKeys2,
-    validateMessage: validateMessage2,
+    extractPlaceholders,
+    computeInvalidIcuKeys,
+    validateMessage,
     validateTree,
     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, keyMode, 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));
+    }
+  };
+}
+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;
@@ -1448,91 +1690,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 icuMessageformatParser.TYPE.argument:
-    case icuMessageformatParser.TYPE.number:
-    case icuMessageformatParser.TYPE.date:
-    case icuMessageformatParser.TYPE.time:
-    case icuMessageformatParser.TYPE.select:
-    case icuMessageformatParser.TYPE.plural:
-      return `{${element.value}}`;
-    case icuMessageformatParser.TYPE.tag:
-      return `<${element.value}>`;
-    default:
-      return void 0;
-  }
-}
-function childMessages(element) {
-  if (element.type === icuMessageformatParser.TYPE.plural || element.type === icuMessageformatParser.TYPE.select) {
-    return Object.values(element.options).map((option) => option.value);
-  }
-  if (element.type === icuMessageformatParser.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 === icuMessageformatParser.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 = icuMessageformatParser.parse(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 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) {
@@ -1594,8 +1758,7 @@ function createNgxTranslateJsonAdapter() {
     }),
     validateTree: assertNotMixed,
     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.
+    // ngx-translate flat style uses dotted keys as path notation, not literal leaves.
     keyMode: "path-notation"
   });
 }
@@ -1671,8 +1834,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 xmldom.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 xmldom.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 xmldom.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 xmldom.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 = yaml.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) => yaml.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
@@ -1687,6 +2087,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 {
@@ -1937,7 +2420,7 @@ async function generatePluralForms(context) {
 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);
@@ -1955,12 +2438,12 @@ function buildRequest3(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 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(
@@ -1974,7 +2457,7 @@ async function runLocale(params) {
     return {
       summary: baseSummary({
         locale: params.targetLocale,
-        unchanged: diff.unchanged,
+        unchanged: diff2.unchanged,
         orphaned,
         invalidIcuSource,
         translated: toTranslate,
@@ -2023,12 +2506,12 @@ async function runLocale(params) {
   return {
     summary: baseSummary({
       locale: params.targetLocale,
-      unchanged: diff.unchanged,
+      unchanged: diff2.unchanged,
       orphaned,
       invalidIcuSource,
       translated: [...accepted.keys()],
       generated: generation.accepted.map((form) => form.targetKey).sort(),
-      // Withheld generated forms surface alongside withheld translations (spec D4): both failed integrity.
+      // Withheld generated forms surface alongside withheld translations: both failed integrity.
       integrityMismatches: [...integrityMismatches, ...generation.withheld].sort(),
       pruned,
       notices
@@ -2152,26 +2635,6 @@ function carryGeneratedLock(lockEntries, baseline, key, sourceBaseKeys) {
   }
 }
 
-// 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/translate-project.ts
 async function translate2(input, deps = {}) {
   const config = input.config;
@@ -2380,7 +2843,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",
@@ -2435,7 +2898,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 = zod.z.object({
@@ -2544,7 +3007,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() };
@@ -2552,7 +3015,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) {
@@ -2570,14 +3033,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;
   }
@@ -2591,10 +3054,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,
@@ -2664,7 +3127,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));
@@ -2673,8 +3136,8 @@ 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,
@@ -2701,7 +3164,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() };
@@ -2740,7 +3203,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,
@@ -2810,6 +3273,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 = chokidar.watch([...paths], { persistent: true, ignoreInitial: true });
   return {
@@ -2918,10 +3391,13 @@ async function watch(input, deps = {}) {
 
 exports.DEFAULT_WORKBOOK_PATH = DEFAULT_WORKBOOK_PATH;
 exports.SdkError = SdkError;
+exports.check = check;
 exports.defineConfig = defineConfig;
+exports.diff = diff;
 exports.exportWorkbook = exportWorkbook;
 exports.importWorkbook = importWorkbook;
 exports.loadConfig = loadConfig;
+exports.scaffoldingMetadata = scaffoldingMetadata;
 exports.translate = translate2;
 exports.verbatraConfigSchema = verbatraConfigSchema;
 exports.watch = watch;