@verbatra/sdk 0.5.0-next.3 → 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));
@@ -922,7 +1018,34 @@ 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) {
@@ -1426,6 +1549,7 @@ 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) {
@@ -1474,7 +1598,23 @@ 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"]
@@ -1908,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) {
@@ -1936,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;
@@ -1954,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));
 }
@@ -1981,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) {
@@ -1999,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;
@@ -2125,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)) {
@@ -2148,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);
@@ -2216,9 +2388,9 @@ function toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTre
   try {
     const tree = parse3(content);
     validateTree?.(tree);
-    const entries = flattenTree(tree, namespace, deriveEntry, keyMode);
-    mergeDescriptions(entries, content, deriveDescriptions);
-    return entries;
+    const result = flattenTree(tree, namespace, deriveEntry, keyMode);
+    mergeDescriptions(result.entries, content, deriveDescriptions);
+    return result;
   } catch (error) {
     rethrowStructured(error, "The file could not be parsed.");
   }
@@ -2249,7 +2421,7 @@ function createTreeFileAdapter(options) {
     async read(filePath, locale) {
       const content = await readFileContent(filePath);
       const namespace = namespaceOf(filePath);
-      const entries = toEntries(
+      const { entries, excludedLeafPaths } = toEntries(
         content,
         namespace,
         parse3,
@@ -2260,7 +2432,7 @@ function createTreeFileAdapter(options) {
       );
       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);
@@ -2354,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)) {
@@ -2449,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(".")) {
@@ -2465,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;
@@ -2626,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);
@@ -3080,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) {
@@ -3099,8 +3313,10 @@ function failureSummary(locale, error) {
     invalidIcuSource: [],
     integrityMismatches: [],
     providerFailures: [],
+    budgetWithheld: [],
     generated: [],
     notices: [],
+    needsReview: [],
     error: describeError(error)
   };
 }
@@ -3270,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({
@@ -3309,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;
@@ -3336,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);
@@ -3409,6 +3683,7 @@ async function runLocale(params) {
         generated: [],
         integrityMismatches: [],
         providerFailures: [],
+        budgetWithheld: [],
         pruned,
         notices: sdkNotices
       }),
@@ -3416,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) {
@@ -3451,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,
@@ -3473,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,
@@ -3493,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 [];
@@ -3516,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));
@@ -3543,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);
@@ -3606,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);
@@ -3630,7 +3966,8 @@ async function translate2(input, deps = {}) {
         prune,
         generatePlurals,
         maxBatchSize,
-        fs
+        fs,
+        budget
       };
       const { summary, lockEntries } = await runLocale(params);
       if (!dryRun) {
@@ -3643,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;
@@ -3684,7 +4033,9 @@ var COLUMN = {
   status: 4,
   translation: 5,
   sourceHash: 6,
-  context: 7
+  context: 7,
+  reviewStatus: 8,
+  reviewReasons: 9
 };
 var HEADERS = [
   "Key",
@@ -3693,7 +4044,9 @@ var HEADERS = [
   "Status",
   "Translation",
   "Source hash",
-  "Context"
+  "Context",
+  "Review status",
+  "Review reasons"
 ];
 var HEADER_ROW = 1;
 var INSTRUCTIONS_SHEET_NAME = "Instructions";
@@ -3713,7 +4066,9 @@ var COLUMN_WIDTHS = {
   [COLUMN.current]: 50,
   [COLUMN.status]: 12,
   [COLUMN.translation]: 50,
-  [COLUMN.context]: 50
+  [COLUMN.context]: 50,
+  [COLUMN.reviewStatus]: 12,
+  [COLUMN.reviewReasons]: 40
 };
 var TEXT_NUMBER_FORMAT = "@";
 function styleHeader(sheet) {
@@ -3745,7 +4100,9 @@ function writeRow(sheet, sheetRow) {
   translationCell.value = sheetRow.translation === "" ? null : sheetRow.translation;
   row.getCell(COLUMN.sourceHash).value = sheetRow.sourceHash;
   row.getCell(COLUMN.context).value = sheetRow.context;
-  for (let column = COLUMN.key; column <= COLUMN.context; column += 1) {
+  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) {
@@ -3920,7 +4277,11 @@ var rowSchema = z.object({
   status: z.enum(["new", "changed", "unchanged"]),
   sourceHash: z.string(),
   translation: z.string(),
-  context: 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;
@@ -3956,7 +4317,10 @@ function parseRow(sheet, row) {
     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))
+    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) {
@@ -4030,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) => {
@@ -4039,14 +4430,23 @@ 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: "",
-        context: sourceEntry.description ?? ""
+        context: sourceEntry.description ?? "",
+        ...computeRowReview(
+          adapter,
+          sourceEntry.value,
+          currentTarget,
+          source.locale,
+          target.locale,
+          glossary
+        )
       });
     }
   };
@@ -4072,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 };
     })
@@ -4173,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 };
 }