@verbatra/sdk 0.5.0-next.2 → 0.5.0-next.4

package/dist/index.js

@@ -472,6 +472,76 @@ function validateRequest(request) {
   }
   return parsed.data;
 }
+var LENGTH_RATIO_MIN = 0.35;
+var LENGTH_RATIO_MAX = 3;
+var LENGTH_RATIO_MIN_SOURCE_LENGTH = 12;
+var UNICODE_LETTER = /\p{L}/u;
+var DEGRADATION_NOTICE_CODES = /* @__PURE__ */ new Set([
+  "FORMALITY_DOWNGRADED",
+  "GLOSSARY_IGNORED"
+]);
+function isLengthRatioOutlier(sourceValue, translatedValue) {
+  const trimmedSource = sourceValue.trim();
+  if (trimmedSource.length < LENGTH_RATIO_MIN_SOURCE_LENGTH) {
+    return false;
+  }
+  const ratio = translatedValue.trim().length / trimmedSource.length;
+  return ratio < LENGTH_RATIO_MIN || ratio > LENGTH_RATIO_MAX;
+}
+function isEqualsSource(input) {
+  const trimmedSource = input.sourceValue.trim();
+  const trimmedTranslated = input.translatedValue.trim();
+  return trimmedTranslated === trimmedSource && input.targetLocale !== input.sourceLocale && UNICODE_LETTER.test(trimmedSource);
+}
+function isGlossaryTermMissed(input) {
+  const glossary = input.glossary;
+  if (glossary === void 0 || Object.keys(glossary).length === 0) {
+    return false;
+  }
+  const sourceLower = input.sourceValue.toLowerCase();
+  const translatedLower = input.translatedValue.toLowerCase();
+  for (const [sourceTerm, targetTerm] of Object.entries(glossary)) {
+    const sourceHit = sourceLower.includes(sourceTerm.toLowerCase());
+    const targetHit = translatedLower.includes(targetTerm.toLowerCase());
+    if (sourceHit && !targetHit) {
+      return true;
+    }
+  }
+  return false;
+}
+function isIntegrityReordered(integrity) {
+  return integrity.matches && integrity.reordered;
+}
+function computeReviewFlags(input) {
+  const reasons = [];
+  if (isLengthRatioOutlier(input.sourceValue, input.translatedValue)) {
+    reasons.push("LENGTH_RATIO_OUTLIER");
+  }
+  if (isEqualsSource(input)) {
+    reasons.push("EQUALS_SOURCE");
+  }
+  if (isGlossaryTermMissed(input)) {
+    reasons.push("GLOSSARY_TERM_MISSED");
+  }
+  if (isIntegrityReordered(input.integrity)) {
+    reasons.push("INTEGRITY_REORDERED");
+  }
+  return reasons.length > 0 ? { status: "review", reasons } : void 0;
+}
+function applyProviderDegraded(reviewFlags, notices, acceptedKeys) {
+  if (!notices.some((notice) => DEGRADATION_NOTICE_CODES.has(notice.code))) {
+    return reviewFlags;
+  }
+  const next = new Map(reviewFlags);
+  for (const key of acceptedKeys) {
+    const existing = next.get(key);
+    next.set(key, {
+      status: "review",
+      reasons: existing !== void 0 ? [...existing.reasons, "PROVIDER_DEGRADED"] : ["PROVIDER_DEGRADED"]
+    });
+  }
+  return next;
+}
 function toIntegrityInputs(entries, values) {
   const inputs = [];
   for (const entry of entries) {
@@ -567,7 +637,33 @@ async function runLlmTranslation(request, mechanism) {
     request.extractPlaceholders,
     request.comparePlaceholders
   );
-  return usage === void 0 ? { values, integrity, notices: [] } : { values, integrity, usage, notices: [] };
+  const notices = [];
+  const reviewFlags = applyProviderDegraded(buildReviewFlags(data, values, integrity), notices, [
+    ...values.keys()
+  ]);
+  return usage === void 0 ? { values, integrity, notices, reviewFlags } : { values, integrity, usage, notices, reviewFlags };
+}
+function buildReviewFlags(data, values, integrity) {
+  const reviewFlags = /* @__PURE__ */ new Map();
+  for (const entry of data.entries) {
+    const translatedValue = values.get(entry.key);
+    const entryIntegrity = integrity.get(entry.key);
+    if (translatedValue === void 0 || entryIntegrity === void 0) {
+      continue;
+    }
+    const flag = computeReviewFlags({
+      sourceValue: entry.value,
+      translatedValue,
+      sourceLocale: data.sourceLocale,
+      targetLocale: data.targetLocale,
+      integrity: entryIntegrity,
+      glossary: data.glossary
+    });
+    if (flag !== void 0) {
+      reviewFlags.set(entry.key, flag);
+    }
+  }
+  return reviewFlags;
 }
 async function requestTranslations(mechanism, data, signal) {
   const payloadJson = JSON.stringify(buildDataPayload(data));
@@ -777,6 +873,50 @@ function createDefaultClient2() {
   };
   return { client, freeAccount };
 }
+var DEEPL_MAX_TEXTS_PER_REQUEST = 50;
+var DEEPL_MAX_PAYLOAD_BYTES = 128 * 1024;
+var DEEPL_PAYLOAD_OVERHEAD_RESERVE_BYTES = 4 * 1024;
+var DEEPL_MAX_TEXT_PAYLOAD_BYTES = DEEPL_MAX_PAYLOAD_BYTES - DEEPL_PAYLOAD_OVERHEAD_RESERVE_BYTES;
+function estimateWireBytes(text) {
+  return encodeURIComponent(text).length;
+}
+function chunkTextsForDeepL(texts) {
+  const chunks = [];
+  let current = [];
+  let currentBytes = 0;
+  for (const text of texts) {
+    const textBytes = estimateWireBytes(text);
+    const startsNewChunk = current.length > 0 && (current.length >= DEEPL_MAX_TEXTS_PER_REQUEST || currentBytes + textBytes > DEEPL_MAX_TEXT_PAYLOAD_BYTES);
+    if (startsNewChunk) {
+      chunks.push(current);
+      current = [];
+      currentBytes = 0;
+    }
+    current.push(text);
+    currentBytes += textBytes;
+  }
+  if (current.length > 0) {
+    chunks.push(current);
+  }
+  return chunks;
+}
+var DEPRECATED_BARE_TARGET_CODES = /* @__PURE__ */ new Set(["en", "pt"]);
+function assertValidDeepLSourceLocale(locale) {
+  if (locale.includes("-")) {
+    throw new ProviderError(
+      "INVALID_REQUEST",
+      `DeepL does not accept a regional or script source locale code: "${locale}". Only the base language code is valid as a DeepL source (for example, use "en" instead of "en-US").`
+    );
+  }
+}
+function assertValidDeepLTargetLocale(locale) {
+  if (DEPRECATED_BARE_TARGET_CODES.has(locale.toLowerCase())) {
+    throw new ProviderError(
+      "INVALID_REQUEST",
+      `DeepL requires a disambiguated target locale code instead of "${locale}" (for example, "en-GB" or "en-US" for English, "pt-PT" or "pt-BR" for Portuguese).`
+    );
+  }
+}
 var PLACEHOLDER_UNSUPPORTED_MESSAGE = "Some entries contain placeholders or ICU syntax that DeepL cannot preserve; they were left untranslated. Use an LLM provider to translate placeholder-bearing strings.";
 function partitionByPlaceholders(entries) {
   const protectable = [];
@@ -856,6 +996,8 @@ function resolveClient(deps) {
 }
 async function translate(bundle, config, request) {
   const data = validateRequest(request);
+  assertValidDeepLSourceLocale(data.sourceLocale);
+  assertValidDeepLTargetLocale(data.targetLocale);
   const { protectable, unprotectable } = partitionByPlaceholders(data.entries);
   const genericGlossarySupplied = request.glossary !== void 0 && Object.keys(request.glossary).length > 0;
   const { options, notices } = buildTranslateOptions({
@@ -876,14 +1018,41 @@ async function translate(bundle, config, request) {
   if (unprotectable.length > 0) {
     notices.push({ code: "PLACEHOLDER_UNSUPPORTED", message: PLACEHOLDER_UNSUPPORTED_MESSAGE });
   }
-  return { values, integrity, notices };
+  const reviewFlags = applyProviderDegraded(
+    buildReviewFlags2(protectable, data, values, integrity, request.glossary),
+    notices,
+    [...values.keys()]
+  );
+  return { values, integrity, notices, reviewFlags };
+}
+function buildReviewFlags2(protectable, data, values, integrity, glossary) {
+  const reviewFlags = /* @__PURE__ */ new Map();
+  for (const entry of protectable) {
+    const translatedValue = values.get(entry.key);
+    const entryIntegrity = integrity.get(entry.key);
+    if (translatedValue === void 0 || entryIntegrity === void 0) {
+      continue;
+    }
+    const flag = computeReviewFlags({
+      sourceValue: entry.value,
+      translatedValue,
+      sourceLocale: data.sourceLocale,
+      targetLocale: data.targetLocale,
+      integrity: entryIntegrity,
+      glossary
+    });
+    if (flag !== void 0) {
+      reviewFlags.set(entry.key, flag);
+    }
+  }
+  return reviewFlags;
 }
 async function translateProtectable(client, data, protectable, options, extract, compare, signal) {
   if (protectable.length === 0) {
     return { values: /* @__PURE__ */ new Map(), integrity: /* @__PURE__ */ new Map() };
   }
   const texts = protectable.map((entry) => entry.value);
-  const results = await callClient2(
+  const results = await callClientChunked(
     client,
     texts,
     data.sourceLocale,
@@ -901,6 +1070,14 @@ function callClient2(client, texts, sourceLang, targetLang, options, signal) {
     signal
   );
 }
+async function callClientChunked(client, texts, sourceLang, targetLang, options, signal) {
+  const results = [];
+  for (const chunk2 of chunkTextsForDeepL(texts)) {
+    const chunkResults = await callClient2(client, chunk2, sourceLang, targetLang, options, signal);
+    results.push(...chunkResults);
+  }
+  return results;
+}
 var geminiConfigSchema = z.object({
   model: z.string().min(1),
   maxOutputTokens: z.number().int().positive()
@@ -1372,6 +1549,18 @@ function buildProvider(config) {
 
 // src/config/schema.ts
 var DEFAULT_MAX_BATCH_SIZE = 50;
+var DEFAULT_BUDGET_BEHAVIOR = "warn";
+function findCaseInsensitiveDuplicate(locales) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const locale of locales) {
+    const key = locale.toLowerCase();
+    if (seen.has(key)) {
+      return locale;
+    }
+    seen.add(key);
+  }
+  return void 0;
+}
 var verbatraConfigSchema = z.strictObject({
   sourceLocale: z.string().min(1),
   targetLocales: z.array(z.string().min(1)).min(1),
@@ -1409,10 +1598,34 @@ var verbatraConfigSchema = z.strictObject({
    * 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()
+  maxBatchSize: z.number().int().positive().optional(),
+  /**
+   * Optional whole-run token ceiling (input plus output tokens summed across every provider call, main
+   * translation and plural generation alike, across all target locales). Checked after each completed
+   * sub-batch, never mid-batch: the sub-batch whose completion crosses the ceiling is retained and
+   * counted, since a call already in flight cannot be undone. Must be a positive integer. Config-only,
+   * no CLI flag. Absent means no budget is enforced. Inert (never a false trip) against a token-less
+   * provider such as DeepL, since it never reports usage to measure against the ceiling.
+   */
+  maxTokens: z.number().int().positive().optional(),
+  /**
+   * What happens once `maxTokens` is reached: `"warn"` (default) flags it and lets the run continue
+   * unchanged; `"stop"` withholds every not-yet-attempted key for the rest of the run (the current
+   * locale's remaining candidates and every later locale's), retried automatically next run. Present
+   * without `maxTokens` is accepted and has no effect. Never changes the command's exit code.
+   */
+  budgetBehavior: z.enum(["warn", "stop"]).optional()
 }).refine((config) => !config.targetLocales.includes(config.sourceLocale), {
   message: "targetLocales must not include the source locale",
   path: ["targetLocales"]
+}).refine((config) => findCaseInsensitiveDuplicate(config.targetLocales) === void 0, {
+  error: (issue) => {
+    const duplicate = findCaseInsensitiveDuplicate(
+      issue.input.targetLocales
+    );
+    return `targetLocales must not contain case-insensitively duplicate locales: "${duplicate}"`;
+  },
+  path: ["targetLocales"]
 }).refine((config) => config.files.pattern.includes(LOCALE_TOKEN), {
   message: `files.pattern must contain the ${LOCALE_TOKEN} token`,
   path: ["files", "pattern"]
@@ -1835,7 +2048,7 @@ var AdapterError = class extends Error {
 var MAX_DEPTH = 100;
 var MAX_INPUT_BYTES = 16 * 1024 * 1024;
 var jsonTreeSchema = z.lazy(
-  () => z.union([z.string(), z.record(z.string(), jsonTreeSchema)])
+  () => z.union([z.string(), z.number(), z.boolean(), z.null(), z.record(z.string(), jsonTreeSchema)])
 );
 var rootSchema = z.record(z.string(), jsonTreeSchema);
 function assertWithinDepth(value, max) {
@@ -1863,7 +2076,7 @@ function assertJsonRecord(value) {
   if (!result.success) {
     throw new AdapterError(
       "INVALID_STRUCTURE",
-      "The file is not a valid object (expected nested objects of string values)."
+      "The file is not a valid object (expected nested objects of string, number, boolean, or null leaves)."
     );
   }
   return result.data;
@@ -1881,6 +2094,9 @@ function serializeJsonTree(tree) {
   return `${JSON.stringify(tree, null, 2)}
 `;
 }
+function isJsonNode(value) {
+  return typeof value === "object" && value !== null;
+}
 function namespaceOf(filePath) {
   return basename(filePath, extname(filePath));
 }
@@ -1908,9 +2124,25 @@ function buildCanHandle(extensions, sniff) {
     return sample === void 0 || sniff === void 0 || sniff(sample);
   };
 }
+async function fsyncPath(path) {
+  const handle = await open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function fsyncDirBestEffort(path) {
+  try {
+    await fsyncPath(path);
+  } catch {
+  }
+}
 var nodeOps = {
   writeFile: (path, data) => writeFile(path, data, "utf8"),
+  fsyncFile: (path) => fsyncPath(path),
   rename: (from, to) => rename(from, to),
+  fsyncDir: (path) => fsyncDirBestEffort(path),
   rm: (path) => rm(path, { force: true })
 };
 async function cleanup(ops, tmp) {
@@ -1926,11 +2158,16 @@ async function atomicWriteFile(path, data, ops = nodeOps) {
   const tmp = tempFileName2(path);
   try {
     await ops.writeFile(tmp, data);
+    await ops.fsyncFile(tmp);
     await ops.rename(tmp, path);
   } catch (error) {
     await cleanup(ops, tmp);
     throw error;
   }
+  try {
+    await ops.fsyncDir(dirname(path));
+  } catch {
+  }
 }
 function stripLeadingBom(content) {
   return content.charCodeAt(0) === 65279 ? content.slice(1) : content;
@@ -2052,20 +2289,24 @@ function addLeaf(ctx, segments, key, value) {
     );
   }
   ctx.claimed.set(effectivePath, mapKey);
+  if (typeof value !== "string") {
+    ctx.excluded.push(mapKey);
+    return;
+  }
   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 {
+    if (isJsonNode(value)) {
       addEntries(ctx, segments, value);
+    } else {
+      addLeaf(ctx, segments, key, value);
     }
   }
 }
-function addPathEntries(node, prefix, namespace, derive, out, claimedPaths) {
+function addPathEntries(node, prefix, namespace, derive, out, claimedPaths, excluded) {
   for (const [key, value] of Object.entries(node)) {
     const path = prefix === "" ? key : `${prefix}.${key}`;
     if (claimedPaths.has(path)) {
@@ -2075,22 +2316,26 @@ function addPathEntries(node, prefix, namespace, derive, out, claimedPaths) {
       );
     }
     claimedPaths.add(path);
-    if (typeof value === "string") {
+    if (isJsonNode(value)) {
+      addPathEntries(value, path, namespace, derive, out, claimedPaths, excluded);
+    } else 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, claimedPaths);
+      excluded.push(path);
     }
   }
 }
 function flattenTree(tree, namespace, derive, keyMode = "literal-leaf") {
   const out = /* @__PURE__ */ new Map();
   if (keyMode === "path-notation") {
-    addPathEntries(tree, "", namespace, derive, out, /* @__PURE__ */ new Set());
-    return out;
+    const excluded = [];
+    addPathEntries(tree, "", namespace, derive, out, /* @__PURE__ */ new Set(), excluded);
+    return { entries: out, excludedLeafPaths: excluded };
   }
-  addEntries({ namespace, derive, out, claimed: /* @__PURE__ */ new Map() }, [], tree);
-  return out;
+  const ctx = { namespace, derive, out, claimed: /* @__PURE__ */ new Map(), excluded: [] };
+  addEntries(ctx, [], tree);
+  return { entries: out, excludedLeafPaths: ctx.excluded };
 }
 function emptyNode() {
   return /* @__PURE__ */ Object.create(null);
@@ -2128,11 +2373,24 @@ function unflattenEntries(entries) {
   }
   return root;
 }
-function toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTree) {
+function mergeDescriptions(entries, content, deriveDescriptions) {
+  if (!deriveDescriptions) {
+    return;
+  }
+  for (const [key, description] of deriveDescriptions(content)) {
+    const entry = entries.get(key);
+    if (entry !== void 0) {
+      entries.set(key, { ...entry, description });
+    }
+  }
+}
+function toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTree, deriveDescriptions) {
   try {
     const tree = parse3(content);
     validateTree?.(tree);
-    return flattenTree(tree, namespace, deriveEntry, keyMode);
+    const result = flattenTree(tree, namespace, deriveEntry, keyMode);
+    mergeDescriptions(result.entries, content, deriveDescriptions);
+    return result;
   } catch (error) {
     rethrowStructured(error, "The file could not be parsed.");
   }
@@ -2151,6 +2409,7 @@ function createTreeFileAdapter(options) {
     validateTree,
     buildWriteTree,
     comparePlaceholders,
+    deriveDescriptions,
     keyMode = "literal-leaf"
   } = options;
   return {
@@ -2162,10 +2421,18 @@ function createTreeFileAdapter(options) {
     async read(filePath, locale) {
       const content = await readFileContent(filePath);
       const namespace = namespaceOf(filePath);
-      const entries = toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTree);
+      const { entries, excludedLeafPaths } = toEntries(
+        content,
+        namespace,
+        parse3,
+        deriveEntry,
+        keyMode,
+        validateTree,
+        deriveDescriptions
+      );
       const resource = { locale, namespace, format, entries };
       const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys);
-      return { resource, invalidIcuKeys };
+      return { resource, invalidIcuKeys, excludedLeafPaths };
     },
     async write(resource, filePath) {
       const tree = buildWriteTree ? await buildWriteTree(resource.entries, filePath) : unflattenEntries(resource.entries);
@@ -2203,6 +2470,31 @@ function stripArbMetadata(tree) {
 function originalKey(encoded) {
   return decodeKeyToSegments(encoded).join(".");
 }
+function messageKeyForMetadata(key) {
+  return isMetadataKey(key) && !key.startsWith("@@") ? key.slice(1) : null;
+}
+function descriptionOf(value) {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const description = value.description;
+  return typeof description === "string" ? description : void 0;
+}
+function extractArbDescriptions(content) {
+  const tree = parseArbObject(content);
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(tree)) {
+    const messageKey = messageKeyForMetadata(key);
+    if (messageKey === null) {
+      continue;
+    }
+    const description = descriptionOf(value);
+    if (description !== void 0) {
+      out.set(encodeSegment(messageKey), description);
+    }
+  }
+  return out;
+}
 function messagesFromEntries(entries) {
   const out = /* @__PURE__ */ new Map();
   for (const [key, entry] of entries) {
@@ -2234,8 +2526,10 @@ async function buildArbWriteTree(entries, filePath) {
     const translated = isMetadataKey(key) ? void 0 : messages.get(key);
     if (translated !== void 0) {
       consumed.add(key);
+      out[key] = translated;
+    } else if (isMetadataKey(key) || typeof value === "string") {
+      out[key] = value;
     }
-    out[key] = translated ?? value;
   }
   for (const [key, value] of messages) {
     if (!consumed.has(key)) {
@@ -2259,7 +2553,8 @@ function createArbAdapter() {
     computeInvalidIcuKeys: icuInvalidKeys,
     validateMessage: icuIsValid,
     comparePlaceholders: compareIcuPlaceholders,
-    buildWriteTree: buildArbWriteTree
+    buildWriteTree: buildArbWriteTree,
+    deriveDescriptions: extractArbDescriptions
   });
 }
 function createJsonFileAdapter(options) {
@@ -2328,7 +2623,7 @@ function createNextIntlJsonAdapter() {
 }
 function assertNoDottedNestedKey(tree) {
   for (const [key, value] of Object.entries(tree)) {
-    if (typeof value !== "object") {
+    if (!isJsonNode(value)) {
       continue;
     }
     if (key.includes(".")) {
@@ -2344,7 +2639,7 @@ function assertNotMixed(tree) {
   let hasNested = false;
   let hasFlatDottedKey = false;
   for (const [key, value] of Object.entries(tree)) {
-    if (typeof value === "object") {
+    if (isJsonNode(value)) {
       hasNested = true;
     } else if (key.includes(".")) {
       hasFlatDottedKey = true;
@@ -2505,7 +2800,7 @@ function createFlatFileAdapter(options) {
       const entries = toEntries2(content, namespace, parseEntries);
       const resource = { locale, namespace, format, entries };
       const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys);
-      return { resource, invalidIcuKeys };
+      return { resource, invalidIcuKeys, excludedLeafPaths: [] };
     },
     async write(resource, filePath) {
       const data = await serializeEntries(resource.entries, filePath);
@@ -2565,16 +2860,33 @@ function parseXml(content) {
   }
   return { doc, root };
 }
+function firstNoteText(parent) {
+  const note = childByName(parent, "note");
+  if (note === null) {
+    return void 0;
+  }
+  const text = (note.textContent ?? "").trim();
+  return text === "" ? void 0 : text;
+}
+function transUnitDescription(tu) {
+  return firstNoteText(tu);
+}
+function unitDescription(unit) {
+  const notes = childByName(unit, "notes");
+  return notes === null ? void 0 : firstNoteText(notes);
+}
 function walkXliff12(root) {
   const units = [];
   collectByTag(root, "trans-unit").forEach((tu, index) => {
     const source = childByName(tu, "source");
     if (source !== null) {
+      const description = transUnitDescription(tu);
       units.push({
         key: unitKey(tu, index),
         source,
         target: childByName(tu, "target"),
-        container: tu
+        container: tu,
+        ...description !== void 0 ? { description } : {}
       });
     }
   });
@@ -2584,12 +2896,19 @@ function walkXliff20(root) {
   const units = [];
   collectByTag(root, "unit").forEach((unit, index) => {
     const baseKey = unitKey(unit, index);
+    const description = unitDescription(unit);
     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 });
+        units.push({
+          key,
+          source,
+          target: childByName(segment, "target"),
+          container: segment,
+          ...description !== void 0 ? { description } : {}
+        });
       }
     });
   });
@@ -2628,7 +2947,8 @@ function parseXliffEntries(content, namespace) {
       namespace,
       value,
       placeholders: extractXliffPlaceholders(value),
-      isPlural: false
+      isPlural: false,
+      ...unit.description !== void 0 ? { description: unit.description } : {}
     });
   }
   return out;
@@ -2934,6 +3254,46 @@ function selectProvider(config, createProvider = buildProvider) {
   }
 }
 
+// src/flow/budget.ts
+function createBudgetTracker(maxTokens, behavior) {
+  return { maxTokens, behavior, tokensUsed: 0, usageSeen: false, exceeded: false, stopped: false };
+}
+function foldTrackerUsage(tracker, usage) {
+  if (usage === void 0) {
+    return;
+  }
+  tracker.usageSeen = true;
+  tracker.tokensUsed += usage.inputTokens + usage.outputTokens;
+}
+function checkBudgetTrip(tracker) {
+  if (tracker.maxTokens === void 0 || tracker.exceeded || tracker.tokensUsed < tracker.maxTokens) {
+    return false;
+  }
+  tracker.exceeded = true;
+  if (tracker.behavior === "stop") {
+    tracker.stopped = true;
+  }
+  return true;
+}
+function toBudgetSummary(tracker) {
+  if (tracker.maxTokens === void 0) {
+    return void 0;
+  }
+  return {
+    maxTokens: tracker.maxTokens,
+    behavior: tracker.behavior,
+    supported: tracker.usageSeen,
+    tokensUsed: tracker.tokensUsed,
+    exceeded: tracker.exceeded
+  };
+}
+function budgetExceededNotice(tracker) {
+  return {
+    code: "BUDGET_TOKENS_EXCEEDED",
+    message: `The run's cumulative token usage (${tracker.tokensUsed}) reached the configured budget of ${tracker.maxTokens} tokens (behavior: ${tracker.behavior}).`
+  };
+}
+
 // src/flow/locale-failure.ts
 function describeError(error) {
   if (error instanceof Error) {
@@ -2953,8 +3313,10 @@ function failureSummary(locale, error) {
     invalidIcuSource: [],
     integrityMismatches: [],
     providerFailures: [],
+    budgetWithheld: [],
     generated: [],
     notices: [],
+    needsReview: [],
     error: describeError(error)
   };
 }
@@ -3124,7 +3486,43 @@ function planPluralGeneration(source, targetLocale, format) {
   return { items };
 }
 
+// src/flow/usage.ts
+function createUsageAccumulator() {
+  return { total: void 0 };
+}
+function foldUsage(accumulator, usage) {
+  if (usage === void 0) {
+    return;
+  }
+  const prior = accumulator.total ?? { inputTokens: 0, outputTokens: 0 };
+  accumulator.total = {
+    inputTokens: prior.inputTokens + usage.inputTokens,
+    outputTokens: prior.outputTokens + usage.outputTokens
+  };
+}
+function combineUsage(a, b) {
+  if (a === void 0) {
+    return b;
+  }
+  if (b === void 0) {
+    return a;
+  }
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens
+  };
+}
+
 // src/flow/plural-generation.ts
+var EMPTY_RESULT = {
+  accepted: [],
+  withheld: [],
+  providerFailures: [],
+  budgetWithheld: [],
+  notices: [],
+  usage: void 0,
+  tripped: false
+};
 function generatedLockHash(governingEntries, category) {
   const governingHashes = governingEntries.map(contentHash).sort();
   return contentHash({
@@ -3163,23 +3561,45 @@ 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: [], providerFailures: [], notices: [] };
+    return EMPTY_RESULT;
   }
   const accepted = [];
   const withheld = [];
   const providerFailures = [];
+  const budgetWithheld = [];
   const notices = [];
+  const usage = createUsageAccumulator();
+  let tripped = false;
   for (const batch of chunk(stale, context.maxBatchSize)) {
-    const batchNotices = await runGenerationSubBatch(
+    if (context.budget.stopped) {
+      for (const item of batch) {
+        budgetWithheld.push(item.targetKey);
+      }
+      continue;
+    }
+    const subResult = await runGenerationSubBatch(
       context,
       batch,
       accepted,
       withheld,
       providerFailures
     );
-    notices.push(...batchNotices);
+    notices.push(...subResult.notices);
+    foldUsage(usage, subResult.usage);
+    foldTrackerUsage(context.budget, subResult.usage);
+    if (checkBudgetTrip(context.budget)) {
+      tripped = true;
+    }
   }
-  return { accepted, withheld, providerFailures, notices };
+  return {
+    accepted,
+    withheld,
+    providerFailures,
+    budgetWithheld,
+    notices,
+    usage: usage.total,
+    tripped
+  };
 }
 async function runGenerationSubBatch(context, batch, accepted, withheld, providerFailures) {
   let result;
@@ -3190,12 +3610,12 @@ async function runGenerationSubBatch(context, batch, accepted, withheld, provide
     for (const item of batch) {
       providerFailures.push(item.targetKey);
     }
-    return [subBatchFailedNotice(batch.length, error)];
+    return { notices: [subBatchFailedNotice(batch.length, error)], usage: void 0 };
   }
   for (const item of batch) {
     foldGenerationItem(item, result, accepted, withheld, providerFailures);
   }
-  return readNotices(result);
+  return { notices: readNotices(result), usage: result.usage };
 }
 function foldGenerationItem(item, result, accepted, withheld, providerFailures) {
   const value = result.values.get(item.targetKey);
@@ -3263,6 +3683,7 @@ async function runLocale(params) {
         generated: [],
         integrityMismatches: [],
         providerFailures: [],
+        budgetWithheld: [],
         pruned,
         notices: sdkNotices
       }),
@@ -3270,16 +3691,21 @@ async function runLocale(params) {
     };
   }
   const entries = toTranslate.map((key) => params.source.entries.get(key)).filter((entry) => entry !== void 0);
+  const startedStopped = params.budget.stopped;
   const accepted = /* @__PURE__ */ new Map();
   const integrityMismatches = [];
   const providerFailures = [];
-  const subBatchNotices = await translateAndCheck(
+  const budgetWithheld = [];
+  const reviewFlags = /* @__PURE__ */ new Map();
+  const translation = await translateAndCheck(
     provider,
     params,
     entries,
     accepted,
     integrityMismatches,
-    providerFailures
+    providerFailures,
+    budgetWithheld,
+    reviewFlags
   );
   const merged = new Map(target.entries);
   for (const key of pruned) {
@@ -3305,16 +3731,20 @@ async function runLocale(params) {
   const pluralNotices = params.generatePlurals ? pluralNoticeFor(params, merged) : sdkNotices;
   const notices = [
     ...pluralNotices,
-    ...subBatchNotices,
-    ...generation.notices
+    ...translation.notices,
+    ...generation.notices,
+    ...budgetLocaleNotices(params.budget, startedStopped, translation.tripped, generation.tripped)
   ];
   const withheld = /* @__PURE__ */ new Set([
     ...integrityMismatches,
     ...providerFailures,
     ...invalidIcuSource,
     ...generation.withheld,
-    ...generation.providerFailures
+    ...generation.providerFailures,
+    // Source-present keys withheld by the budget guardrail must keep their prior lock hash too.
+    ...budgetWithheld
   ]);
+  const localeUsage = combineUsage(translation.usage, generation.usage);
   return {
     summary: baseSummary({
       locale: params.targetLocale,
@@ -3327,15 +3757,27 @@ async function runLocale(params) {
       integrityMismatches: [...integrityMismatches, ...generation.withheld].sort(),
       // A generation sub-batch whose provider call itself threw is a provider failure, never integrity.
       providerFailures: [...providerFailures, ...generation.providerFailures].sort(),
+      budgetWithheld: [...budgetWithheld, ...generation.budgetWithheld].sort(),
       pruned,
-      notices
+      notices,
+      needsReview: needsReviewFor(accepted.keys(), reviewFlags),
+      ...localeUsage !== void 0 ? { usage: localeUsage } : {}
     }),
     lockEntries: computeLockEntries(params, merged, withheld, generation.accepted)
   };
 }
+var NO_GENERATION_RESULT = {
+  accepted: [],
+  withheld: [],
+  providerFailures: [],
+  budgetWithheld: [],
+  notices: [],
+  usage: void 0,
+  tripped: false
+};
 async function runGeneration(params, provider) {
   if (!params.generatePlurals || provider.kind !== "llm") {
-    return { accepted: [], withheld: [], providerFailures: [], notices: [] };
+    return NO_GENERATION_RESULT;
   }
   return generatePluralForms({
     source: params.source,
@@ -3347,9 +3789,13 @@ async function runGeneration(params, provider) {
     glossary: params.glossary,
     tone: params.tone,
     baseline: params.baseline,
-    maxBatchSize: params.maxBatchSize
+    maxBatchSize: params.maxBatchSize,
+    budget: params.budget
   });
 }
+function budgetLocaleNotices(budget, startedStopped, mainTripped, generationTripped) {
+  return startedStopped || mainTripped || generationTripped ? [budgetExceededNotice(budget)] : [];
+}
 function pluralNoticeFor(params, merged) {
   if (params.format !== "i18next-json") {
     return [];
@@ -3370,26 +3816,53 @@ function baseSummary(parts) {
     invalidIcuSource: parts.invalidIcuSource,
     integrityMismatches: parts.integrityMismatches,
     providerFailures: parts.providerFailures,
+    budgetWithheld: parts.budgetWithheld,
     generated: parts.generated,
-    notices: parts.notices
+    notices: parts.notices,
+    needsReview: parts.needsReview ?? [],
+    ...parts.usage !== void 0 ? { usage: parts.usage } : {}
   };
 }
-async function translateAndCheck(provider, params, entries, accepted, integrityMismatches, providerFailures) {
+function needsReviewFor(acceptedKeys, reviewFlags) {
+  const entries = [];
+  for (const key of acceptedKeys) {
+    const flag = reviewFlags.get(key);
+    if (flag !== void 0) {
+      entries.push({ key, reasons: flag.reasons });
+    }
+  }
+  return entries.sort((a, b) => a.key < b.key ? -1 : 1);
+}
+async function translateAndCheck(provider, params, entries, accepted, integrityMismatches, providerFailures, budgetWithheld, reviewFlags) {
   const notices = [];
+  const usage = createUsageAccumulator();
+  let tripped = false;
   for (const batch of chunk(entries, params.maxBatchSize)) {
-    const subNotices = await runSubBatch(
+    if (params.budget.stopped) {
+      for (const entry of batch) {
+        budgetWithheld.push(entry.key);
+      }
+      continue;
+    }
+    const subResult = await runSubBatch(
       provider,
       params,
       batch,
       accepted,
       integrityMismatches,
-      providerFailures
+      providerFailures,
+      reviewFlags
     );
-    notices.push(...subNotices);
+    notices.push(...subResult.notices);
+    foldUsage(usage, subResult.usage);
+    foldTrackerUsage(params.budget, subResult.usage);
+    if (checkBudgetTrip(params.budget)) {
+      tripped = true;
+    }
   }
-  return notices;
+  return { notices, tripped, usage: usage.total };
 }
-async function runSubBatch(provider, params, batch, accepted, integrityMismatches, providerFailures) {
+async function runSubBatch(provider, params, batch, accepted, integrityMismatches, providerFailures, reviewFlags) {
   let result;
   try {
     result = await provider.translateBatch(buildRequest3(params, batch));
@@ -3397,12 +3870,17 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
     for (const entry of batch) {
       providerFailures.push(entry.key);
     }
-    return [subBatchFailedNotice(batch.length, error)];
+    return { notices: [subBatchFailedNotice(batch.length, error)], usage: void 0 };
   }
   for (const entry of batch) {
     foldEntryResult(entry, result, accepted, integrityMismatches, providerFailures);
   }
-  return readNotices(result);
+  if (result.reviewFlags !== void 0) {
+    for (const [key, flag] of result.reviewFlags) {
+      reviewFlags.set(key, flag);
+    }
+  }
+  return { notices: readNotices(result), usage: result.usage };
 }
 function foldEntryResult(entry, result, accepted, integrityMismatches, providerFailures) {
   const value = result.values.get(entry.key);
@@ -3460,6 +3938,10 @@ async function translate2(input, deps = {}) {
   const generatePlurals = input.generatePlurals ?? config.generatePlurals ?? false;
   const maxBatchSize = config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
   const fs = deps.fs ?? defaultFs;
+  const budget = createBudgetTracker(
+    config.maxTokens,
+    config.budgetBehavior ?? DEFAULT_BUDGET_BEHAVIOR
+  );
   const adapter = selectAdapter(config.format, deps.adapterRegistry);
   const provider = dryRun ? void 0 : selectProvider(config.provider, deps.createProvider);
   const source = await readSource(config, cwd, fs, adapter);
@@ -3484,7 +3966,8 @@ async function translate2(input, deps = {}) {
         prune,
         generatePlurals,
         maxBatchSize,
-        fs
+        fs,
+        budget
       };
       const { summary, lockEntries } = await runLocale(params);
       if (!dryRun) {
@@ -3497,7 +3980,19 @@ async function translate2(input, deps = {}) {
     }
   }
   const { succeeded, failed } = partition(summaries);
-  return { dryRun, locales: summaries, succeeded, failed };
+  const usage = summaries.reduce(
+    (total, summary) => combineUsage(total, summary.usage),
+    void 0
+  );
+  const budgetSummary = toBudgetSummary(budget);
+  return {
+    dryRun,
+    locales: summaries,
+    succeeded,
+    failed,
+    ...usage !== void 0 ? { usage } : {},
+    ...budgetSummary !== void 0 ? { budget: budgetSummary } : {}
+  };
 }
 var ExchangeError = class extends Error {
   code;
@@ -3519,10 +4014,13 @@ var INSTRUCTIONS_LINES = [
   "   structure and the argument names exactly. Translate only the human-readable text.",
   "6. Do not edit the 'Key' column or the hidden 'Source hash' column. They map your translation",
   "   back to the right string. You may sort or filter rows freely; mapping does not depend on row order.",
+  "7. The 'Context' column, when present, is reference text from the source file explaining what the",
+  "   string means or where it is used. It is read-only; leave it as-is.",
   "",
   "Status values:",
   "  new      - this string has no translation yet.",
   "  changed  - the source string changed and the translation needs updating.",
+  "  unchanged - already up to date, included for reference. No action needed.",
   "",
   "When you are done, save the file and send it back. verbatra checks every value on import:",
   "a value with a broken placeholder, invalid ICU, or a source that changed since export is",
@@ -3534,7 +4032,10 @@ var COLUMN = {
   current: 3,
   status: 4,
   translation: 5,
-  sourceHash: 6
+  sourceHash: 6,
+  context: 7,
+  reviewStatus: 8,
+  reviewReasons: 9
 };
 var HEADERS = [
   "Key",
@@ -3542,7 +4043,10 @@ var HEADERS = [
   "Current translation",
   "Status",
   "Translation",
-  "Source hash"
+  "Source hash",
+  "Context",
+  "Review status",
+  "Review reasons"
 ];
 var HEADER_ROW = 1;
 var INSTRUCTIONS_SHEET_NAME = "Instructions";
@@ -3561,7 +4065,10 @@ var COLUMN_WIDTHS = {
   [COLUMN.source]: 50,
   [COLUMN.current]: 50,
   [COLUMN.status]: 12,
-  [COLUMN.translation]: 50
+  [COLUMN.translation]: 50,
+  [COLUMN.context]: 50,
+  [COLUMN.reviewStatus]: 12,
+  [COLUMN.reviewReasons]: 40
 };
 var TEXT_NUMBER_FORMAT = "@";
 function styleHeader(sheet) {
@@ -3592,7 +4099,10 @@ function writeRow(sheet, sheetRow) {
   translationCell.numFmt = TEXT_NUMBER_FORMAT;
   translationCell.value = sheetRow.translation === "" ? null : sheetRow.translation;
   row.getCell(COLUMN.sourceHash).value = sheetRow.sourceHash;
-  for (let column = COLUMN.key; column <= COLUMN.sourceHash; column += 1) {
+  row.getCell(COLUMN.context).value = sheetRow.context;
+  row.getCell(COLUMN.reviewStatus).value = sheetRow.reviewStatus;
+  row.getCell(COLUMN.reviewReasons).value = sheetRow.reviewReasons;
+  for (let column = COLUMN.key; column <= COLUMN.reviewReasons; column += 1) {
     const cell = row.getCell(column);
     cell.protection = { locked: column !== COLUMN.translation };
     if (column !== COLUMN.translation) {
@@ -3617,6 +4127,26 @@ function assertValidWorksheetName(locale) {
     );
   }
 }
+function assertNoWorksheetNameCollisions(sheets) {
+  const reservedKey = INSTRUCTIONS_SHEET_NAME.toLowerCase();
+  const seen = /* @__PURE__ */ new Set();
+  for (const sheet of sheets) {
+    const key = sheet.locale.toLowerCase();
+    if (key === reservedKey) {
+      throw new ExchangeError(
+        "WORKBOOK_INVALID",
+        `The locale "${sheet.locale}" cannot be an Excel worksheet name: it collides with the reserved "${INSTRUCTIONS_SHEET_NAME}" sheet.`
+      );
+    }
+    if (seen.has(key)) {
+      throw new ExchangeError(
+        "WORKBOOK_INVALID",
+        `The locale "${sheet.locale}" cannot be an Excel worksheet name: it collides with another target locale's sheet name.`
+      );
+    }
+    seen.add(key);
+  }
+}
 async function buildDataSheet(workbook, sheet) {
   assertValidWorksheetName(sheet.locale);
   const worksheet = workbook.addWorksheet(sheet.locale);
@@ -3643,6 +4173,7 @@ function buildInstructionsSheet(workbook) {
   sheet.getRow(1).font = { bold: true };
 }
 async function buildWorkbook(model) {
+  assertNoWorksheetNameCollisions(model.sheets);
   const workbook = new ExcelJS.Workbook();
   buildInstructionsSheet(workbook);
   for (const sheet of model.sheets) {
@@ -3743,9 +4274,14 @@ var rowSchema = z.object({
   key: z.string().min(1),
   source: z.string(),
   currentTarget: z.string(),
-  status: z.enum(["new", "changed"]),
+  status: z.enum(["new", "changed", "unchanged"]),
   sourceHash: z.string(),
-  translation: z.string()
+  translation: z.string(),
+  context: z.string(),
+  // A legacy workbook exported before these columns existed has no such cell; cellString then yields
+  // "", and .catch maps it to "ok" / "" rather than rejecting the row.
+  reviewStatus: z.enum(["ok", "review"]).catch("ok"),
+  reviewReasons: z.string().catch("")
 });
 function cellString(cell) {
   const value = cell.value;
@@ -3778,7 +4314,13 @@ function parseRow(sheet, row) {
     currentTarget: cellString(row.getCell(COLUMN.current)),
     status: cellString(row.getCell(COLUMN.status)),
     sourceHash: cellString(row.getCell(COLUMN.sourceHash)),
-    translation: cellString(row.getCell(COLUMN.translation))
+    translation: cellString(row.getCell(COLUMN.translation)),
+    // A workbook built before the Context column existed has no cell here; getCell auto-vivifies an
+    // empty one, so cellString yields "" and the row still validates, keeping import backward-compatible.
+    context: cellString(row.getCell(COLUMN.context)),
+    // Same backward-compatible pattern for a workbook built before the Review columns existed.
+    reviewStatus: cellString(row.getCell(COLUMN.reviewStatus)),
+    reviewReasons: cellString(row.getCell(COLUMN.reviewReasons))
   };
   const result = rowSchema.safeParse(candidate);
   if (!result.success) {
@@ -3852,7 +4394,34 @@ async function readTarget3(cwd, config, adapter, fs, locale) {
   }
   return (await adapter.read(path, locale)).resource;
 }
-function buildRows(source, target, baseline, includeUnchanged) {
+function reasonLabel(reason) {
+  return reason.toLowerCase().replace(/_/g, "-");
+}
+function reviewColumns(flag) {
+  if (flag === void 0) {
+    return { reviewStatus: "ok", reviewReasons: "" };
+  }
+  return { reviewStatus: "review", reviewReasons: flag.reasons.map(reasonLabel).join(", ") };
+}
+function computeRowReview(adapter, sourceValue, currentTarget, sourceLocale, targetLocale, glossary) {
+  if (currentTarget === "") {
+    return { reviewStatus: "ok", reviewReasons: "" };
+  }
+  const integrity = adapter.comparePlaceholders?.(sourceValue, currentTarget) ?? checkPlaceholders(
+    adapter.extractPlaceholders(sourceValue),
+    adapter.extractPlaceholders(currentTarget)
+  );
+  const flag = computeReviewFlags({
+    sourceValue,
+    translatedValue: currentTarget,
+    sourceLocale,
+    targetLocale,
+    integrity,
+    glossary
+  });
+  return reviewColumns(flag);
+}
+function buildRows(source, target, baseline, includeUnchanged, adapter, glossary) {
   const diff2 = diffResources(source, target, { baseline });
   const rows = [];
   const add = (keys, status) => {
@@ -3861,20 +4430,30 @@ function buildRows(source, target, baseline, includeUnchanged) {
       if (sourceEntry === void 0) {
         continue;
       }
+      const currentTarget = target.entries.get(key)?.value ?? "";
       rows.push({
         key,
         source: sourceEntry.value,
-        currentTarget: target.entries.get(key)?.value ?? "",
+        currentTarget,
         status,
         sourceHash: contentHash(sourceEntry),
-        translation: ""
+        translation: "",
+        context: sourceEntry.description ?? "",
+        ...computeRowReview(
+          adapter,
+          sourceEntry.value,
+          currentTarget,
+          source.locale,
+          target.locale,
+          glossary
+        )
       });
     }
   };
   add(diff2.missing, "new");
   add(diff2.changed, "changed");
   if (includeUnchanged) {
-    add(diff2.unchanged, "changed");
+    add(diff2.unchanged, "unchanged");
   }
   return [...rows].sort((a, b) => a.key < b.key ? -1 : 1);
 }
@@ -3893,7 +4472,9 @@ async function exportWorkbook(input, deps = {}) {
         source.resource,
         target,
         baselineFor(lock, locale),
-        input.includeUnchanged ?? false
+        input.includeUnchanged ?? false,
+        adapter,
+        config.glossary
       );
       return { locale, rows };
     })
@@ -3994,9 +4575,14 @@ function importLocale(params) {
     integrityMismatches: [...buckets.mismatches].sort(),
     // A workbook import never calls a provider, so a provider-call failure cannot occur here.
     providerFailures: [],
+    // A workbook import never calls a provider, so the budget guardrail never withholds anything here.
+    budgetWithheld: [],
     // Plural generation is a translate-flow concern; the manual workbook import never generates forms.
     generated: [],
-    notices: buckets.blankDrifted.size > 0 ? [blankRowBaselineNotice(buckets.blankDrifted.size)] : []
+    notices: buckets.blankDrifted.size > 0 ? [blankRowBaselineNotice(buckets.blankDrifted.size)] : [],
+    // A workbook import never calls a provider and never recomputes review flags on its own path; the
+    // Excel workbook's Review status/reasons columns are informational only (see export-workbook.ts).
+    needsReview: []
   };
   return { summary, accepted: buckets.accepted, withheld: buckets.withheld };
 }