@verbatra/sdk 0.6.0 → 0.6.2

package/dist/index.js

@@ -1,10 +1,10 @@
-import { existsSync } from 'fs';
 import { dirname, resolve, join, basename, extname } from 'path';
+import { z } from 'zod';
+import { existsSync } from 'fs';
 import { cosmiconfig } from 'cosmiconfig';
 import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
 import { randomUUID } from 'crypto';
 import { rm, access, mkdir, open, writeFile, rename } from 'fs/promises';
-import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
 import * as deepl from 'deepl-node';
 import { createRequire } from 'module';
@@ -15,10 +15,100 @@ import { parse, TYPE } from '@formatjs/icu-messageformat-parser';
 import { XMLSerializer, DOMParser } from '@xmldom/xmldom';
 import { stringify, parse as parse$1 } from 'yaml';
 import ExcelJS from 'exceljs';
-import { Readable } from 'stream';
 import JSZip from 'jszip';
+import { Readable } from 'stream';
 import { watch as watch$1 } from 'chokidar';
 
+// src/cache/translation-memory.ts
+var CACHE_FILE_NAME = "verbatra.cache.json";
+var CURRENT_VERSION = 1;
+var EMPTY_MEMORY = { version: CURRENT_VERSION, entries: {} };
+var MAX_CACHE_FILE_BYTES = 64 * 1024 * 1024;
+var translationMemorySchema = z.object({
+  version: z.number().int().positive(),
+  entries: z.record(z.string(), z.record(z.string(), z.record(z.string(), z.string())))
+});
+function cacheFilePath(cwd) {
+  return resolve(cwd, CACHE_FILE_NAME);
+}
+async function readTranslationMemory(path, fs) {
+  let read;
+  try {
+    read = await fs.readFileBounded(path, MAX_CACHE_FILE_BYTES);
+  } catch {
+    return EMPTY_MEMORY;
+  }
+  if (read.kind !== "ok") {
+    return EMPTY_MEMORY;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(read.content);
+  } catch {
+    return EMPTY_MEMORY;
+  }
+  const result = translationMemorySchema.safeParse(parsed);
+  if (!result.success || result.data.version !== CURRENT_VERSION) {
+    return EMPTY_MEMORY;
+  }
+  return result.data;
+}
+function lookupMemory(memory, fingerprint, locale, contentHash2) {
+  return memory.entries[fingerprint]?.[locale]?.[contentHash2];
+}
+function applyAdditions(base, fingerprint, additionsByLocale) {
+  if (additionsByLocale.size === 0) {
+    return base;
+  }
+  const fingerprintEntries = {};
+  for (const [locale, hashes] of Object.entries(base.entries[fingerprint] ?? {})) {
+    fingerprintEntries[locale] = { ...hashes };
+  }
+  for (const [locale, hashes] of additionsByLocale) {
+    fingerprintEntries[locale] = { ...fingerprintEntries[locale], ...hashes };
+  }
+  return {
+    version: base.version,
+    entries: { ...base.entries, [fingerprint]: fingerprintEntries }
+  };
+}
+function additionsToRecord(additions) {
+  const record = {};
+  for (const addition of additions) {
+    record[addition.contentHash] = addition.value;
+  }
+  return record;
+}
+function sortEntries(record) {
+  return Object.entries(record).sort(([a], [b]) => a < b ? -1 : 1);
+}
+function serialize(memory) {
+  const entries = {};
+  for (const [fingerprint, locales] of sortEntries(memory.entries)) {
+    const localeMap = {};
+    for (const [locale, hashes] of sortEntries(locales)) {
+      localeMap[locale] = Object.fromEntries(sortEntries(hashes));
+    }
+    entries[fingerprint] = localeMap;
+  }
+  return `${JSON.stringify({ version: memory.version, entries }, null, 2)}
+`;
+}
+async function writeTranslationMemory(path, memory, fs) {
+  await fs.writeFile(path, serialize(memory));
+}
+async function feedTranslationMemory(cwd, fs, fingerprint, additionsByLocale) {
+  if (additionsByLocale.size === 0) {
+    return;
+  }
+  try {
+    const path = cacheFilePath(cwd);
+    const memory = await readTranslationMemory(path, fs);
+    await writeTranslationMemory(path, applyAdditions(memory, fingerprint, additionsByLocale), fs);
+  } catch {
+  }
+}
+
 // src/config/define-config.ts
 function defineConfig(config) {
   return config;
@@ -212,7 +302,7 @@ async function resolveGlossary(glossary, baseDir, fs) {
 var FNV_OFFSET_BASIS = 14695981039346656037n;
 var FNV_PRIME = 1099511628211n;
 var U64_MASK = (1n << 64n) - 1n;
-function fnv1a64(input) {
+function stableStringHash(input) {
   let hash = FNV_OFFSET_BASIS;
   for (let index = 0; index < input.length; index += 1) {
     hash ^= BigInt(input.charCodeAt(index));
@@ -233,7 +323,7 @@ function canonicalize(entry) {
   ]);
 }
 function contentHash(entry) {
-  return fnv1a64(canonicalize(entry));
+  return stableStringHash(canonicalize(entry));
 }
 function sorted(keys) {
   return [...keys].sort();
@@ -278,7 +368,8 @@ var SUPPORTED_FORMATS = [
   "ngx-translate-json",
   "xliff",
   "yaml",
-  "arb"
+  "arb",
+  "properties"
 ];
 var supportedFormatSchema = z.enum(SUPPORTED_FORMATS);
 var translationEntrySchema = z.object({
@@ -329,77 +420,76 @@ function checkPlaceholders(source, translated) {
     reordered
   };
 }
-var LOCALE_TOKEN = "{locale}";
-function localeFilePath(cwd, pattern, locale) {
-  return resolve(cwd, pattern.replaceAll(LOCALE_TOKEN, locale));
-}
-var RATE_LIMITED_STATUS = 429;
-var TIMEOUT_STATUS = 408;
-var AUTH_FAILED_STATUSES = /* @__PURE__ */ new Set([401, 403]);
-var RATE_LIMITED_CLASS_NAMES = /* @__PURE__ */ new Set([
-  "RateLimitError",
-  "TooManyRequestsError"
-]);
-var AUTH_FAILED_CLASS_NAMES = /* @__PURE__ */ new Set([
-  "AuthenticationError",
-  "PermissionDeniedError",
-  "AuthorizationError"
-]);
-var TIMEOUT_CLASS_NAMES = /* @__PURE__ */ new Set([
-  "APIConnectionTimeoutError",
-  "ConnectionError"
-]);
-var ABORT_ERROR_CLASS_NAMES = /* @__PURE__ */ new Set(["APIUserAbortError"]);
-function getErrorStatus(error) {
-  if (typeof error !== "object" || error === null || !("status" in error)) {
-    return void 0;
+var MIN_SOURCE_LENGTH = 8;
+var MAX_LENGTH_MULTIPLE = 12;
+var MAX_REPEAT_UNIT_LENGTH = 16;
+var MIN_CONSECUTIVE_REPEATS = 8;
+var REPEAT_COVERAGE_FRACTION = 0.5;
+var MAX_SCAN_LENGTH = 8192;
+function matchesUnit(text, a, b, unit) {
+  for (let i = 0; i < unit; i++) {
+    if (text[a + i] !== text[b + i]) {
+      return false;
+    }
   }
-  const status = error.status;
-  return typeof status === "number" ? status : void 0;
+  return true;
 }
-function readClassName(error) {
-  if (typeof error !== "object" || error === null) {
-    return void 0;
+function countConsecutiveCopies(text, start, unit, scanLength) {
+  let copies = 1;
+  let next = start + unit;
+  while (next + unit <= scanLength && matchesUnit(text, start, next, unit)) {
+    copies++;
+    next += unit;
+  }
+  return copies;
+}
+function hasDominantRun(text, scanLength, unit, coverage) {
+  const limit = scanLength - unit;
+  let start = 0;
+  while (start <= limit) {
+    const copies = countConsecutiveCopies(text, start, unit, scanLength);
+    if (copies >= MIN_CONSECUTIVE_REPEATS && copies * unit >= coverage) {
+      return true;
+    }
+    start += copies * unit;
   }
-  return error.constructor?.name;
+  return false;
 }
-function classifyProviderError(error) {
-  const status = getErrorStatus(error);
-  if (status === RATE_LIMITED_STATUS) {
-    return "RATE_LIMITED";
-  }
-  if (status !== void 0 && AUTH_FAILED_STATUSES.has(status)) {
-    return "AUTH_FAILED";
-  }
-  if (status === TIMEOUT_STATUS) {
-    return "TIMEOUT";
-  }
-  const className = readClassName(error);
-  if (className !== void 0) {
-    if (RATE_LIMITED_CLASS_NAMES.has(className)) {
-      return "RATE_LIMITED";
-    }
-    if (AUTH_FAILED_CLASS_NAMES.has(className)) {
-      return "AUTH_FAILED";
-    }
-    if (TIMEOUT_CLASS_NAMES.has(className)) {
-      return "TIMEOUT";
+function hasRunawayRepetition(text) {
+  const scanLength = Math.min(text.length, MAX_SCAN_LENGTH);
+  const coverage = scanLength * REPEAT_COVERAGE_FRACTION;
+  const maxUnit = Math.min(
+    MAX_REPEAT_UNIT_LENGTH,
+    Math.floor(scanLength / MIN_CONSECUTIVE_REPEATS)
+  );
+  for (let unit = 1; unit <= maxUnit; unit++) {
+    if (hasDominantRun(text, scanLength, unit, coverage)) {
+      return true;
     }
   }
-  return "PROVIDER_ERROR";
+  return false;
 }
-function isAbortShapedError(error) {
-  if (error instanceof Error && error.name === "AbortError") {
-    return true;
+function assessValueDegeneracy(sourceValue, candidateValue) {
+  const source = sourceValue.trim();
+  const candidate = candidateValue.trim();
+  if (source.length >= MIN_SOURCE_LENGTH && candidate.length >= source.length * MAX_LENGTH_MULTIPLE) {
+    return { degenerate: true };
   }
-  const className = readClassName(error);
-  return className !== void 0 && ABORT_ERROR_CLASS_NAMES.has(className);
+  return { degenerate: hasRunawayRepetition(candidate) };
 }
-function isAbortError(error, signal) {
-  if (signal !== void 0) {
-    return signal.aborted === true && isAbortShapedError(error);
+var LOCALE_TOKEN = "{locale}";
+function localeFilePath(cwd, pattern, locale) {
+  return resolve(cwd, pattern.replaceAll(LOCALE_TOKEN, locale));
+}
+function checkBatchIntegrity(inputs, extract, compare) {
+  const integrity = /* @__PURE__ */ new Map();
+  for (const { key, sourceValue, translatedValue } of inputs) {
+    integrity.set(
+      key,
+      compare !== void 0 ? compare(sourceValue, translatedValue) : checkPlaceholders(extract(sourceValue), extract(translatedValue))
+    );
   }
-  return isAbortShapedError(error);
+  return integrity;
 }
 var REDACTED = "[REDACTED]";
 var KEY_PATTERNS = [
@@ -437,38 +527,6 @@ var ProviderError = class extends Error {
     this.code = code;
   }
 };
-var PROVIDER_CALL_FAILED_MESSAGE = "The translation provider request failed.";
-var RATE_LIMITED_MESSAGE = "The translation provider rate-limited this request.";
-var TIMEOUT_MESSAGE = "The translation provider request timed out.";
-var AUTH_FAILED_MESSAGE = "The translation provider rejected the request credentials.";
-var MESSAGE_BY_CODE = {
-  RATE_LIMITED: RATE_LIMITED_MESSAGE,
-  TIMEOUT: TIMEOUT_MESSAGE,
-  AUTH_FAILED: AUTH_FAILED_MESSAGE,
-  PROVIDER_ERROR: PROVIDER_CALL_FAILED_MESSAGE
-};
-async function guardProviderCall(call, signal) {
-  signal?.throwIfAborted();
-  try {
-    return await call();
-  } catch (error) {
-    if (isAbortError(error, signal)) {
-      throw error;
-    }
-    const code = classifyProviderError(error);
-    throw new ProviderError(code, MESSAGE_BY_CODE[code]);
-  }
-}
-function checkBatchIntegrity(inputs, extract, compare) {
-  const integrity = /* @__PURE__ */ new Map();
-  for (const { key, sourceValue, translatedValue } of inputs) {
-    integrity.set(
-      key,
-      compare !== void 0 ? compare(sourceValue, translatedValue) : checkPlaceholders(extract(sourceValue), extract(translatedValue))
-    );
-  }
-  return integrity;
-}
 var requestDataSchema = z.object({
   sourceLocale: z.string().min(1),
   targetLocale: z.string().min(1),
@@ -711,6 +769,121 @@ function assertNotTruncated(truncated) {
     throw new ProviderError("OUTPUT_TRUNCATED", OUTPUT_TRUNCATED_MESSAGE);
   }
 }
+var RATE_LIMITED_STATUS = 429;
+var TIMEOUT_STATUS = 408;
+var AUTH_FAILED_STATUSES = /* @__PURE__ */ new Set([401, 403]);
+var RATE_LIMITED_CLASS_NAMES = /* @__PURE__ */ new Set([
+  "RateLimitError",
+  "TooManyRequestsError"
+]);
+var AUTH_FAILED_CLASS_NAMES = /* @__PURE__ */ new Set([
+  "AuthenticationError",
+  "PermissionDeniedError",
+  "AuthorizationError"
+]);
+var TIMEOUT_CLASS_NAMES = /* @__PURE__ */ new Set([
+  "APIConnectionTimeoutError",
+  "ConnectionError"
+]);
+var ABORT_ERROR_CLASS_NAMES = /* @__PURE__ */ new Set(["APIUserAbortError"]);
+function getErrorStatus(error) {
+  if (typeof error !== "object" || error === null || !("status" in error)) {
+    return void 0;
+  }
+  const status = error.status;
+  return typeof status === "number" ? status : void 0;
+}
+function readClassName(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  return error.constructor?.name;
+}
+function classifyProviderError(error) {
+  const status = getErrorStatus(error);
+  if (status === RATE_LIMITED_STATUS) {
+    return "RATE_LIMITED";
+  }
+  if (status !== void 0 && AUTH_FAILED_STATUSES.has(status)) {
+    return "AUTH_FAILED";
+  }
+  if (status === TIMEOUT_STATUS) {
+    return "TIMEOUT";
+  }
+  const className = readClassName(error);
+  if (className !== void 0) {
+    if (RATE_LIMITED_CLASS_NAMES.has(className)) {
+      return "RATE_LIMITED";
+    }
+    if (AUTH_FAILED_CLASS_NAMES.has(className)) {
+      return "AUTH_FAILED";
+    }
+    if (TIMEOUT_CLASS_NAMES.has(className)) {
+      return "TIMEOUT";
+    }
+  }
+  return "PROVIDER_ERROR";
+}
+function isAbortShapedError(error) {
+  if (error instanceof Error && error.name === "AbortError") {
+    return true;
+  }
+  const className = readClassName(error);
+  return className !== void 0 && ABORT_ERROR_CLASS_NAMES.has(className);
+}
+function isAbortError(error, signal) {
+  if (signal !== void 0) {
+    return signal.aborted === true && isAbortShapedError(error);
+  }
+  return isAbortShapedError(error);
+}
+var PROVIDER_CALL_FAILED_MESSAGE = "The translation provider request failed.";
+var RATE_LIMITED_MESSAGE = "The translation provider rate-limited this request.";
+var TIMEOUT_MESSAGE = "The translation provider request timed out.";
+var AUTH_FAILED_MESSAGE = "The translation provider rejected the request credentials.";
+var MESSAGE_BY_CODE = {
+  RATE_LIMITED: RATE_LIMITED_MESSAGE,
+  TIMEOUT: TIMEOUT_MESSAGE,
+  AUTH_FAILED: AUTH_FAILED_MESSAGE,
+  PROVIDER_ERROR: PROVIDER_CALL_FAILED_MESSAGE
+};
+async function guardProviderCall(call, signal) {
+  signal?.throwIfAborted();
+  try {
+    return await call();
+  } catch (error) {
+    if (isAbortError(error, signal)) {
+      throw error;
+    }
+    const code = classifyProviderError(error);
+    throw new ProviderError(code, MESSAGE_BY_CODE[code]);
+  }
+}
+var DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
+function requestTimedOutMessage(timeoutMs) {
+  return `The translation provider request exceeded the ${timeoutMs} ms request timeout.`;
+}
+function combineSignals(caller, timeout) {
+  return caller === void 0 ? timeout : AbortSignal.any([caller, timeout]);
+}
+async function withRequestTimeout(timeoutMs, callerSignal, call) {
+  const timeoutController = new AbortController();
+  const signal = combineSignals(callerSignal, timeoutController.signal);
+  let timer;
+  const timedOut = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      timeoutController.abort();
+      reject(new ProviderError("TIMEOUT", requestTimedOutMessage(timeoutMs)));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([guardProviderCall(() => call(signal), signal), timedOut]);
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  }
+}
 var PROVIDER_ENV = {
   anthropic: "ANTHROPIC_API_KEY",
   openai: "OPENAI_API_KEY",
@@ -765,7 +938,13 @@ function createDefaultClient() {
 }
 var anthropicConfigSchema = z.object({
   model: z.string().min(1),
-  maxTokens: z.number().int().positive()
+  maxTokens: z.number().int().positive(),
+  /**
+   * Optional verbatra-imposed per-request timeout in milliseconds. A positive integer; when absent,
+   * the shared default request timeout applies. Bounds each outbound request so a hung-but-alive
+   * server cannot hold a locale's write lock open forever.
+   */
+  requestTimeoutMs: z.number().int().positive().optional()
 });
 var SUBMIT_TOOL_NAME = "submit_translations";
 var SYSTEM_RULES = [
@@ -825,10 +1004,11 @@ function createAnthropicProvider(config, deps = {}) {
   };
 }
 function createMechanism(client, config) {
+  const timeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
   return {
     translate: async ({ payloadJson, signal }) => {
       const body = buildRequest(config, payloadJson);
-      const message = await callClient(client, body, signal);
+      const message = await callClient(client, body, timeoutMs, signal);
       assertNotTruncated(message.stop_reason === "max_tokens");
       const raw = requireToolInput(message.content);
       const usage = toUsage(message.usage);
@@ -836,10 +1016,11 @@ function createMechanism(client, config) {
     }
   };
 }
-function callClient(client, body, signal) {
-  return guardProviderCall(
-    () => client.messages.create(body, signal !== void 0 ? { signal } : void 0),
-    signal
+function callClient(client, body, timeoutMs, signal) {
+  return withRequestTimeout(
+    timeoutMs,
+    signal,
+    (requestSignal) => client.messages.create(body, { signal: requestSignal })
   );
 }
 function toUsage(usage) {
@@ -853,7 +1034,14 @@ function toUsage(usage) {
   return { inputTokens: input_tokens, outputTokens: output_tokens };
 }
 var deepLConfigSchema = z.object({
-  glossaryId: z.string().min(1).optional()
+  glossaryId: z.string().min(1).optional(),
+  /**
+   * Optional verbatra-imposed per-request timeout in milliseconds. A positive integer; when absent,
+   * the shared default request timeout applies. Bounds each outbound request so a hung-but-alive
+   * server cannot hold a locale's write lock open forever. deepl-node cannot cancel an in-flight
+   * request, so on timeout verbatra's await is released but the underlying request is left to settle.
+   */
+  requestTimeoutMs: z.number().int().positive().optional()
 });
 var DEEPL_LOGGER = "deepl";
 function resolveDeeplLoglevel(requireFn = createRequire(import.meta.url)) {
@@ -1024,6 +1212,7 @@ async function translate(bundle, config, request) {
     options,
     request.extractPlaceholders,
     request.comparePlaceholders,
+    config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
     request.signal
   );
   if (unprotectable.length > 0) {
@@ -1058,7 +1247,7 @@ function buildReviewFlags2(protectable, data, values, integrity, glossary) {
   }
   return reviewFlags;
 }
-async function translateProtectable(client, data, protectable, options, extract, compare, signal) {
+async function translateProtectable(client, data, protectable, options, extract, compare, timeoutMs, signal) {
   if (protectable.length === 0) {
     return { values: /* @__PURE__ */ new Map(), integrity: /* @__PURE__ */ new Map() };
   }
@@ -1069,29 +1258,45 @@ async function translateProtectable(client, data, protectable, options, extract,
     data.sourceLocale,
     data.targetLocale,
     options,
+    timeoutMs,
     signal
   );
   const { values, integrityInputs } = zipResults(protectable, results);
   const integrity = checkBatchIntegrity(integrityInputs, extract, compare);
   return { values, integrity };
 }
-function callClient2(client, texts, sourceLang, targetLang, options, signal) {
-  return guardProviderCall(
-    () => client.translateText(texts, sourceLang, targetLang, options),
-    signal
+function callClient2(client, texts, sourceLang, targetLang, options, timeoutMs, signal) {
+  return withRequestTimeout(
+    timeoutMs,
+    signal,
+    () => client.translateText(texts, sourceLang, targetLang, options)
   );
 }
-async function callClientChunked(client, texts, sourceLang, targetLang, options, signal) {
+async function callClientChunked(client, texts, sourceLang, targetLang, options, timeoutMs, signal) {
   const results = [];
   for (const chunk2 of chunkTextsForDeepL(texts)) {
-    const chunkResults = await callClient2(client, chunk2, sourceLang, targetLang, options, signal);
+    const chunkResults = await callClient2(
+      client,
+      chunk2,
+      sourceLang,
+      targetLang,
+      options,
+      timeoutMs,
+      signal
+    );
     results.push(...chunkResults);
   }
   return results;
 }
 var geminiConfigSchema = z.object({
   model: z.string().min(1),
-  maxOutputTokens: z.number().int().positive()
+  maxOutputTokens: z.number().int().positive(),
+  /**
+   * Optional verbatra-imposed per-request timeout in milliseconds. A positive integer; when absent,
+   * the shared default request timeout applies. Bounds each outbound request so a hung-but-alive
+   * server cannot hold a locale's write lock open forever.
+   */
+  requestTimeoutMs: z.number().int().positive().optional()
 });
 var DEFAULT_GEMINI_RETRY = { attempts: 3, baseDelayMs: 250 };
 function isRetryableStatus(error) {
@@ -1106,14 +1311,14 @@ function throwAbort(signal) {
   throw new DOMException("This operation was aborted.", "AbortError");
 }
 function delay(ms, signal) {
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     const onAbort = () => {
       clearTimeout(timer);
-      resolve9();
+      resolve10();
     };
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve9();
+      resolve10();
     }, ms);
     signal?.addEventListener("abort", onAbort, { once: true });
   });
@@ -1281,20 +1486,27 @@ function createGeminiProvider(config, deps = {}) {
   };
 }
 function createMechanism2(client, config) {
+  const timeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
   return {
     translate: async ({ payloadJson, signal }) => {
-      const request = buildGeminiRequest(config, payloadJson, signal);
-      const response = await callClient3(client, request, signal);
+      const response = await withRequestTimeout(
+        timeoutMs,
+        signal,
+        (requestSignal) => client.models.generateContent(buildGeminiRequest(config, payloadJson, requestSignal))
+      );
       return extractGeminiResult(response);
     }
   };
 }
-function callClient3(client, request, signal) {
-  return guardProviderCall(() => client.models.generateContent(request), signal);
-}
 var openAiConfigSchema = z.object({
   model: z.string().min(1),
-  maxOutputTokens: z.number().int().positive()
+  maxOutputTokens: z.number().int().positive(),
+  /**
+   * Optional verbatra-imposed per-request timeout in milliseconds. A positive integer; when absent,
+   * the shared default request timeout applies. Bounds each outbound request so a hung-but-alive
+   * server cannot hold a locale's write lock open forever.
+   */
+  requestTimeoutMs: z.number().int().positive().optional()
 });
 function createDefaultClient4() {
   const sdk = new OpenAI({ apiKey: requireOpenAiKey(), logLevel: "off" });
@@ -1449,18 +1661,20 @@ function createOpenAiProvider(config, deps = {}) {
   };
 }
 function createMechanism3(client, config) {
+  const timeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
   return {
     translate: async ({ payloadJson, signal }) => {
       const body = buildOpenAiRequest(config, payloadJson);
-      const completion = await callClient4(client, body, signal);
+      const completion = await callClient3(client, body, timeoutMs, signal);
       return extractOpenAiResult(completion);
     }
   };
 }
-function callClient4(client, body, signal) {
-  return guardProviderCall(
-    () => client.chat.completions.create(body, signal !== void 0 ? { signal } : void 0),
-    signal
+function callClient3(client, body, timeoutMs, signal) {
+  return withRequestTimeout(
+    timeoutMs,
+    signal,
+    (requestSignal) => client.chat.completions.create(body, { signal: requestSignal })
   );
 }
 var HOSTED_PROVIDER_ENV_VARS = new Set(
@@ -1483,7 +1697,13 @@ var openAiCompatibleConfigSchema = z.object({
   maxOutputTokens: z.number().int().positive(),
   apiKeyEnvVar: z.string().min(1).refine(isNotHostedProviderEnvVar, {
     message: "apiKeyEnvVar must not name a hosted provider's environment variable."
-  }).optional()
+  }).optional(),
+  /**
+   * Optional verbatra-imposed per-request timeout in milliseconds. A positive integer; when absent,
+   * the shared default request timeout applies. Bounds each outbound request so a hung-but-alive local
+   * server (the reported stuck-LM-Studio case) cannot hold a locale's write lock open forever.
+   */
+  requestTimeoutMs: z.number().int().positive().optional()
 });
 function createDefaultClient5(config) {
   const sdk = new OpenAI({
@@ -1515,18 +1735,20 @@ function createOpenAiCompatibleProvider(config, deps = {}) {
   };
 }
 function createMechanism4(client, config) {
+  const timeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
   return {
     translate: async ({ payloadJson, signal }) => {
       const body = buildOpenAiRequest(config, payloadJson, "strict-schema", "max_tokens");
-      const completion = await callClient5(client, body, signal);
+      const completion = await callClient4(client, body, timeoutMs, signal);
       return extractOpenAiResult(completion, true);
     }
   };
 }
-function callClient5(client, body, signal) {
-  return guardProviderCall(
-    () => client.chat.completions.create(body, signal !== void 0 ? { signal } : void 0),
-    signal
+function callClient4(client, body, timeoutMs, signal) {
+  return withRequestTimeout(
+    timeoutMs,
+    signal,
+    (requestSignal) => client.chat.completions.create(body, { signal: requestSignal })
   );
 }
 var SCAFFOLD_MODELS = {
@@ -1736,6 +1958,8 @@ var LOCAL_DIR_NAME = ".verbatra-local";
 var LOCK_FILE_GUARD_STEM = "_lockfile";
 var DEFAULT_POLL_INTERVAL_MS = 100;
 var DEFAULT_ACQUIRE_TIMEOUT_MS = 10 * 6e4;
+var WAIT_NOTICE_INTERVAL_MS = 1e3;
+var MAX_LOCK_PAYLOAD_BYTES = 64 * 1024;
 function lockPath(cwd, stem) {
   return resolve(cwd, LOCAL_DIR_NAME, "locks", `${stem}.lock`);
 }
@@ -1753,7 +1977,47 @@ function sleep(ms) {
 function lockPayload() {
   return JSON.stringify({ pid: process.pid, acquiredAt: (/* @__PURE__ */ new Date()).toISOString() });
 }
-async function acquireLock(path, fs, pollIntervalMs, deadline) {
+function parseHolder(read) {
+  if (read.kind !== "ok") {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(read.content);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return void 0;
+  }
+  const record = parsed;
+  const holder = {};
+  if (typeof record.pid === "number") {
+    holder.pid = record.pid;
+  }
+  if (typeof record.acquiredAt === "string") {
+    holder.acquiredAt = record.acquiredAt;
+  }
+  return holder;
+}
+function makeWaitNotifier(path, fs, onWait, start) {
+  let holder;
+  let holderRead = false;
+  let lastEmit;
+  return async () => {
+    if (!holderRead) {
+      holderRead = true;
+      holder = parseHolder(await fs.readFileBounded(path, MAX_LOCK_PAYLOAD_BYTES));
+    }
+    const elapsedMs = Date.now() - start;
+    if (lastEmit !== void 0 && elapsedMs - lastEmit < WAIT_NOTICE_INTERVAL_MS) {
+      return;
+    }
+    lastEmit = elapsedMs;
+    onWait({ lockPath: path, elapsedMs, ...holder !== void 0 ? { holder } : {} });
+  };
+}
+async function acquireLock(path, fs, pollIntervalMs, deadline, notify) {
   for (; ; ) {
     if (await fs.createExclusive(path, lockPayload())) {
       return;
@@ -1764,6 +2028,9 @@ async function acquireLock(path, fs, pollIntervalMs, deadline) {
         `Could not acquire the write lock at ${path}: another process may be holding it. If no verbatra process is currently running, this lock file was likely left behind by one that was killed; delete it and retry.`
       );
     }
+    if (notify !== void 0) {
+      await notify();
+    }
     const jitter = Math.random() * pollIntervalMs;
     await sleep(pollIntervalMs + jitter);
   }
@@ -1771,7 +2038,9 @@ async function acquireLock(path, fs, pollIntervalMs, deadline) {
 async function withFileLock(path, fs, fn, options) {
   const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
   const acquireTimeoutMs = options.acquireTimeoutMs ?? DEFAULT_ACQUIRE_TIMEOUT_MS;
-  await acquireLock(path, fs, pollIntervalMs, Date.now() + acquireTimeoutMs);
+  const start = Date.now();
+  const notify = options.onWait !== void 0 ? makeWaitNotifier(path, fs, options.onWait, start) : void 0;
+  await acquireLock(path, fs, pollIntervalMs, start + acquireTimeoutMs, notify);
   try {
     return await fn();
   } finally {
@@ -1787,8 +2056,8 @@ async function withLockFileGuard(cwd, fs, fn, options = {}) {
 
 // src/lock/lock-file.ts
 var LOCK_FILE_NAME = "verbatra.lock.json";
-var CURRENT_VERSION = 1;
-var EMPTY_LOCK = { version: CURRENT_VERSION, locales: {} };
+var CURRENT_VERSION2 = 1;
+var EMPTY_LOCK = { version: CURRENT_VERSION2, locales: {} };
 var MAX_LOCK_FILE_BYTES = 16 * 1024 * 1024;
 var lockFileSchema = z.object({
   version: z.number().int().positive(),
@@ -1817,10 +2086,10 @@ function parseLockFileRead(read, path) {
   if (!result.success) {
     throw new SdkError("LOCK_FILE_INVALID", `The lock-file at ${path} has an unexpected shape.`);
   }
-  if (result.data.version !== CURRENT_VERSION) {
+  if (result.data.version !== CURRENT_VERSION2) {
     throw new SdkError(
       "LOCK_FILE_INVALID",
-      `The lock-file at ${path} has version ${result.data.version}, but this version of verbatra supports version ${CURRENT_VERSION}.`
+      `The lock-file at ${path} has version ${result.data.version}, but this version of verbatra supports version ${CURRENT_VERSION2}.`
     );
   }
   return result.data;
@@ -2610,7 +2879,7 @@ function createTreeFileAdapter(options) {
     extensions,
     sniff,
     parse: parse3,
-    serialize,
+    serialize: serialize2,
     deriveEntry,
     extractPlaceholders,
     computeInvalidIcuKeys,
@@ -2645,7 +2914,7 @@ function createTreeFileAdapter(options) {
     },
     async write(resource, filePath) {
       const tree = buildWriteTree ? await buildWriteTree(resource.entries, filePath) : unflattenEntries(resource.entries);
-      await atomicWriteFile(filePath, serialize(tree));
+      await atomicWriteFile(filePath, serialize2(tree));
     }
   };
 }
@@ -2864,42 +3133,429 @@ async function detectStyle(filePath) {
     if (outcome.kind !== "ok") {
       return "nested";
     }
-    parsed = JSON.parse(outcome.content);
-  } catch {
-    return "nested";
+    parsed = JSON.parse(outcome.content);
+  } catch {
+    return "nested";
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return "nested";
+  }
+  for (const value of Object.values(parsed)) {
+    if (typeof value === "object" && value !== null) {
+      return "nested";
+    }
+  }
+  return "flat";
+}
+function buildFlatTree(entries) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, entry] of entries) {
+    out.set(key, entry.value);
+  }
+  return out;
+}
+async function buildNgxWriteTree(entries, filePath) {
+  const style = await detectStyle(filePath);
+  return style === "flat" ? buildFlatTree(entries) : unflattenEntries(entries);
+}
+function createNgxTranslateJsonAdapter() {
+  return createJsonFileAdapter({
+    format: "ngx-translate-json",
+    extractPlaceholders: extractDoubleBracePlaceholders,
+    deriveEntry: (_key, value) => ({
+      placeholders: extractDoubleBracePlaceholders(value),
+      isPlural: false
+    }),
+    validateTree: assertNotMixed,
+    buildWriteTree: buildNgxWriteTree,
+    keyMode: "path-notation"
+  });
+}
+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, excludedLeafPaths: [] };
+    },
+    async write(resource, filePath) {
+      const data = await serializeEntries(resource.entries, filePath);
+      await atomicWriteFile(filePath, data);
+    }
+  };
+}
+var SUBMESSAGE_TYPES = /* @__PURE__ */ new Set(["plural", "select", "selectordinal", "choice"]);
+var ARGUMENT_NAME = /^(?:\d+|[A-Za-z_$][\w$-]*)$/;
+function matchingBraces(value) {
+  const close = new Int32Array(value.length).fill(-1);
+  const open3 = [];
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (char === "{") {
+      open3.push(i);
+    } else if (char === "}") {
+      const start = open3.pop();
+      if (start !== void 0) {
+        close[start] = i;
+      }
+    }
+  }
+  return close;
+}
+function findNameEnd(value, from, limit) {
+  for (let i = from; i < limit; i += 1) {
+    const char = value[i];
+    if (char === ",") {
+      return { comma: i, hasBrace: false };
+    }
+    if (char === "{" || char === "}") {
+      return { comma: -1, hasBrace: true };
+    }
+  }
+  return { comma: -1, hasBrace: false };
+}
+function parseArgumentAt(value, open3, close) {
+  const { comma, hasBrace } = findNameEnd(value, open3 + 1, close);
+  if (hasBrace) {
+    return null;
+  }
+  const nameEnd = comma === -1 ? close : comma;
+  const name = value.slice(open3 + 1, nameEnd).trim();
+  if (!ARGUMENT_NAME.test(name)) {
+    return null;
+  }
+  if (comma === -1) {
+    return { name, type: null, styleStart: -1 };
+  }
+  const secondComma = value.indexOf(",", comma + 1);
+  if (secondComma === -1 || secondComma >= close) {
+    return { name, type: value.slice(comma + 1, close).trim(), styleStart: -1 };
+  }
+  return { name, type: value.slice(comma + 1, secondComma).trim(), styleStart: secondComma + 1 };
+}
+function canonicalToken(value, arg, close) {
+  if (arg.type === null) {
+    return `{${arg.name}}`;
+  }
+  if (arg.styleStart === -1) {
+    return `{${arg.name},${arg.type}}`;
+  }
+  return `{${arg.name},${arg.type},${value.slice(arg.styleStart, close).trim()}}`;
+}
+function emitArgument(value, close, arg, closeIndex, out) {
+  if (arg.type !== null && SUBMESSAGE_TYPES.has(arg.type)) {
+    out.push(`{${arg.name},${arg.type}}`);
+    if (arg.styleStart !== -1) {
+      scanRange(value, close, arg.styleStart, closeIndex, false, out);
+    }
+    return;
+  }
+  out.push(canonicalToken(value, arg, closeIndex));
+}
+function scanRange(value, close, start, end, topLevel, out) {
+  let i = start;
+  while (i < end) {
+    if (value[i] !== "{") {
+      i += 1;
+      continue;
+    }
+    if (topLevel && value[i + 1] === "{") {
+      i += 2;
+      continue;
+    }
+    const closeIndex = close[i] ?? -1;
+    if (closeIndex === -1 || closeIndex >= end) {
+      i += 1;
+      continue;
+    }
+    const arg = parseArgumentAt(value, i, closeIndex);
+    if (arg === null) {
+      i += 1;
+      continue;
+    }
+    emitArgument(value, close, arg, closeIndex, out);
+    i = closeIndex + 1;
+  }
+}
+function extractPropertiesPlaceholders(value) {
+  const out = [];
+  scanRange(value, matchingBraces(value), 0, value.length, true, out);
+  return out;
+}
+var UNICODE_ESCAPE = /^[0-9a-fA-F]{4}$/;
+var LEADING_WHITESPACE = /^[ \t\f]+/;
+var TRAILING_TERMINATOR = /(?:\r\n|\r|\n)$/;
+function isPropertiesWhitespace(char) {
+  return char === " " || char === "	" || char === "\f";
+}
+function splitPhysicalLines(content) {
+  if (content === "") {
+    return [];
+  }
+  const lines = content.split(/\r\n|\r|\n/);
+  if (TRAILING_TERMINATOR.test(content)) {
+    lines.pop();
+  }
+  return lines;
+}
+function countTrailingBackslashes(line) {
+  let count = 0;
+  for (let i = line.length - 1; i >= 0 && line[i] === "\\"; i -= 1) {
+    count += 1;
+  }
+  return count;
+}
+function isContinued(line) {
+  return countTrailingBackslashes(line) % 2 === 1;
+}
+function isBlankLine(line) {
+  return line.trim() === "";
+}
+function isCommentLine(line) {
+  const trimmed = line.replace(LEADING_WHITESPACE, "");
+  return trimmed.startsWith("#") || trimmed.startsWith("!");
+}
+function joinContinuation(lines, start) {
+  const pieces = [];
+  let index = start;
+  let current = lines[start] ?? "";
+  while (isContinued(current) && index + 1 < lines.length) {
+    pieces.push(current.slice(0, -1));
+    index += 1;
+    current = (lines[index] ?? "").replace(LEADING_WHITESPACE, "");
+  }
+  if (isContinued(current)) {
+    current = current.slice(0, -1);
+  }
+  pieces.push(current);
+  return { logical: pieces.join(""), nextIndex: index + 1 };
+}
+function decodeSimpleEscape(char) {
+  switch (char) {
+    case "t":
+      return "	";
+    case "n":
+      return "\n";
+    case "r":
+      return "\r";
+    case "f":
+      return "\f";
+    default:
+      return char;
+  }
+}
+function decodeUnicodeEscape(raw, at) {
+  const hex = raw.slice(at, at + 4);
+  if (!UNICODE_ESCAPE.test(hex)) {
+    throw new AdapterError("INVALID_STRUCTURE", "The file has a malformed unicode escape.");
+  }
+  return String.fromCharCode(Number.parseInt(hex, 16));
+}
+function decodeEscapes(raw) {
+  let out = "";
+  let i = 0;
+  while (i < raw.length) {
+    const char = raw[i];
+    if (char !== "\\") {
+      out += char;
+      i += 1;
+      continue;
+    }
+    const next = raw[i + 1];
+    if (next === void 0) {
+      break;
+    }
+    if (next === "u") {
+      out += decodeUnicodeEscape(raw, i + 2);
+      i += 6;
+      continue;
+    }
+    out += decodeSimpleEscape(next);
+    i += 2;
+  }
+  return out;
+}
+function keyEndIndex(logical, from) {
+  let i = from;
+  while (i < logical.length) {
+    const char = logical[i];
+    if (char === "\\") {
+      i += 2;
+      continue;
+    }
+    if (char === void 0 || isPropertiesWhitespace(char) || char === "=" || char === ":") {
+      break;
+    }
+    i += 1;
+  }
+  return i;
+}
+function skipWhitespace(logical, from) {
+  let i = from;
+  while (i < logical.length) {
+    const char = logical[i];
+    if (char === void 0 || !isPropertiesWhitespace(char)) {
+      break;
+    }
+    i += 1;
+  }
+  return i;
+}
+function parseEntryLine(logical) {
+  const keyStart = skipWhitespace(logical, 0);
+  const keyEnd = keyEndIndex(logical, keyStart);
+  const afterKey = skipWhitespace(logical, keyEnd);
+  const separator = logical[afterKey];
+  const valueStart = separator === "=" || separator === ":" ? skipWhitespace(logical, afterKey + 1) : afterKey;
+  return {
+    key: decodeEscapes(logical.slice(keyStart, keyEnd)),
+    value: decodeEscapes(logical.slice(valueStart))
+  };
+}
+function parseItems(content) {
+  const lines = splitPhysicalLines(content);
+  const items = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    if (isBlankLine(line) || isCommentLine(line)) {
+      items.push({ kind: "raw", text: line });
+      i += 1;
+      continue;
+    }
+    const { logical, nextIndex } = joinContinuation(lines, i);
+    items.push({ kind: "entry", ...parseEntryLine(logical) });
+    i = nextIndex;
+  }
+  return items;
+}
+function parsePropertiesEntries(content, namespace) {
+  const map = /* @__PURE__ */ new Map();
+  for (const item of parseItems(content)) {
+    if (item.kind === "entry") {
+      map.set(item.key, {
+        key: item.key,
+        namespace,
+        value: item.value,
+        placeholders: extractPropertiesPlaceholders(item.value),
+        isPlural: false
+      });
+    }
+  }
+  return map;
+}
+function unicodeEscape(code) {
+  return `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+function escapeChar(char, isFirst, isKey) {
+  switch (char) {
+    case "\\":
+      return "\\\\";
+    case "	":
+      return "\\t";
+    case "\n":
+      return "\\n";
+    case "\r":
+      return "\\r";
+    case "\f":
+      return "\\f";
+    case " ":
+      return isKey || isFirst ? "\\ " : " ";
+  }
+  if (isKey && (char === "=" || char === ":" || char === "#" || char === "!")) {
+    return `\\${char}`;
+  }
+  const code = char.charCodeAt(0);
+  return code < 32 || code > 126 ? unicodeEscape(code) : char;
+}
+function escapeString(input, isKey) {
+  let out = "";
+  for (let i = 0; i < input.length; i += 1) {
+    const char = input[i];
+    if (char !== void 0) {
+      out += escapeChar(char, i === 0, isKey);
+    }
+  }
+  return out;
+}
+function formatEntry(key, value) {
+  return `${escapeString(key, true)}=${escapeString(value, false)}`;
+}
+function isFileNotFound(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function readStructure(filePath) {
+  let outcome;
+  try {
+    outcome = await readBounded2(filePath);
+  } catch (error) {
+    if (isFileNotFound(error)) {
+      return [];
+    }
+    throw new AdapterError("INVALID_STRUCTURE", "The destination file could not be read.");
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    return "nested";
+  if (outcome.kind === "not-a-file") {
+    throw new AdapterError("INVALID_STRUCTURE", "The destination path is not a regular file.");
   }
-  for (const value of Object.values(parsed)) {
-    if (typeof value === "object" && value !== null) {
-      return "nested";
-    }
+  if (outcome.kind === "too-large") {
+    throw new AdapterError("INPUT_TOO_LARGE", "The file exceeds the maximum allowed size.");
   }
-  return "flat";
+  return parseItems(outcome.content);
 }
-function buildFlatTree(entries) {
-  const out = /* @__PURE__ */ new Map();
+async function serializePropertiesEntries(entries, filePath) {
+  const structure = await readStructure(filePath);
+  const emitted = /* @__PURE__ */ new Set();
+  const lines = [];
+  for (const item of structure) {
+    if (item.kind === "raw") {
+      lines.push(item.text);
+      continue;
+    }
+    const entry = entries.get(item.key);
+    if (entry !== void 0 && !emitted.has(item.key)) {
+      lines.push(formatEntry(item.key, entry.value));
+      emitted.add(item.key);
+    }
+  }
   for (const [key, entry] of entries) {
-    out.set(key, entry.value);
+    if (!emitted.has(key)) {
+      lines.push(formatEntry(key, entry.value));
+    }
   }
-  return out;
-}
-async function buildNgxWriteTree(entries, filePath) {
-  const style = await detectStyle(filePath);
-  return style === "flat" ? buildFlatTree(entries) : unflattenEntries(entries);
+  return lines.length === 0 ? "" : `${lines.join("\n")}
+`;
 }
-function createNgxTranslateJsonAdapter() {
-  return createJsonFileAdapter({
-    format: "ngx-translate-json",
-    extractPlaceholders: extractDoubleBracePlaceholders,
-    deriveEntry: (_key, value) => ({
-      placeholders: extractDoubleBracePlaceholders(value),
-      isPlural: false
-    }),
-    validateTree: assertNotMixed,
-    buildWriteTree: buildNgxWriteTree,
-    keyMode: "path-notation"
+function createPropertiesAdapter() {
+  return createFlatFileAdapter({
+    format: "properties",
+    extensions: [".properties"],
+    parseEntries: parsePropertiesEntries,
+    serializeEntries: serializePropertiesEntries,
+    extractPlaceholders: extractPropertiesPlaceholders
   });
 }
 var AdapterRegistry = class {
@@ -2979,43 +3635,6 @@ 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, excludedLeafPaths: [] };
-    },
-    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 = [];
@@ -3326,7 +3945,7 @@ function createYamlAdapter() {
   });
 }
 function createDefaultRegistry() {
-  return new AdapterRegistry().register(createI18nextJsonAdapter()).register(createVueI18nJsonAdapter()).register(createNextIntlJsonAdapter()).register(createNgxTranslateJsonAdapter()).register(createXliffAdapter()).register(createYamlAdapter()).register(createArbAdapter());
+  return new AdapterRegistry().register(createI18nextJsonAdapter()).register(createVueI18nJsonAdapter()).register(createNextIntlJsonAdapter()).register(createNgxTranslateJsonAdapter()).register(createXliffAdapter()).register(createYamlAdapter()).register(createArbAdapter()).register(createPropertiesAdapter());
 }
 
 // src/selection/select-adapter.ts
@@ -3447,6 +4066,28 @@ async function diff(input, deps = {}) {
   return { hasPendingChanges: locales.some((entry) => entry.hasPendingChanges), locales };
 }
 
+// src/cache/fingerprint.ts
+function fingerprintModel(provider) {
+  const options = provider.options;
+  const model = options.model;
+  return typeof model === "string" ? model : null;
+}
+function sortGlossary(glossary) {
+  if (glossary === void 0) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(glossary).sort(([a], [b]) => a < b ? -1 : 1));
+}
+function computeFingerprint(config) {
+  const canonical = JSON.stringify({
+    provider: config.provider.id,
+    model: fingerprintModel(config.provider),
+    tone: config.tone ?? null,
+    glossary: sortGlossary(config.glossary)
+  });
+  return stableStringHash(canonical);
+}
+
 // src/flow/integrity-gate.ts
 function gateCandidateValue(sourceEntry, candidateValue, adapter) {
   const placeholderResult = adapter.comparePlaceholders?.(sourceEntry.value, candidateValue) ?? checkPlaceholders(sourceEntry.placeholders, adapter.extractPlaceholders(candidateValue));
@@ -3456,6 +4097,9 @@ function gateCandidateValue(sourceEntry, candidateValue, adapter) {
   if (!adapter.validateMessage(candidateValue)) {
     return { accepted: false, reason: "icu" };
   }
+  if (assessValueDegeneracy(sourceEntry.value, candidateValue).degenerate) {
+    return { accepted: false, reason: "degenerate" };
+  }
   return { accepted: true };
 }
 
@@ -3494,6 +4138,12 @@ async function editEntry(input, deps = {}) {
       mode: "merge",
       entries: { [input.key]: contentHash(sourceEntry) }
     });
+    await feedTranslationMemory(
+      cwd,
+      fs,
+      computeFingerprint(config),
+      /* @__PURE__ */ new Map([[locale, { [contentHash(sourceEntry)]: input.value }]])
+    );
     return { accepted: true, value: input.value };
   });
 }
@@ -3711,13 +4361,19 @@ async function retranslateEntry(input, deps = {}) {
       mode: "merge",
       entries: { [input.key]: contentHash(sourceEntry) }
     });
+    await feedTranslationMemory(
+      cwd,
+      fs,
+      computeFingerprint(config),
+      /* @__PURE__ */ new Map([[locale, { [contentHash(sourceEntry)]: value }]])
+    );
     const reviewReasons = result.reviewFlags?.get(input.key)?.reasons ?? [];
     return { accepted: true, value, reviewReasons };
   });
 }
 var RUN_STATUS_DIR_NAME = ".verbatra-local";
 var RUN_STATUS_FILE_NAME = "run-status.json";
-var CURRENT_VERSION2 = 1;
+var CURRENT_VERSION3 = 1;
 var MAX_RUN_STATUS_FILE_BYTES = 16 * 1024 * 1024;
 var reviewReasonCodeSchema = z.enum([
   "LENGTH_RATIO_OUTLIER",
@@ -3743,7 +4399,7 @@ var runBudgetSchema = z.object({
 });
 var runStatusLocaleSchema = z.object({
   locale: z.string(),
-  status: z.enum(["succeeded", "failed"]),
+  status: z.enum(["succeeded", "partial", "failed"]),
   needsReview: z.array(needsReviewEntrySchema),
   usage: usageSummarySchema.optional()
 });
@@ -3767,7 +4423,7 @@ function toRunStatusLocale(locale) {
 }
 function buildRunStatusFile(summary, generatedAt = (/* @__PURE__ */ new Date()).toISOString()) {
   return {
-    version: CURRENT_VERSION2,
+    version: CURRENT_VERSION3,
     generatedAt,
     ...summary.usage !== void 0 ? { usage: summary.usage } : {},
     ...summary.budget !== void 0 ? { budget: summary.budget } : {},
@@ -3800,7 +4456,7 @@ async function readRunStatusFile(path, fs) {
     return void 0;
   }
   const result = runStatusFileSchema.safeParse(parsed);
-  if (!result.success || result.data.version !== CURRENT_VERSION2) {
+  if (!result.success || result.data.version !== CURRENT_VERSION3) {
     return void 0;
   }
   return fromParsed(result.data);
@@ -3879,19 +4535,34 @@ function failureSummary(locale, error) {
     orphaned: [],
     pruned: [],
     invalidIcuSource: [],
+    cacheHits: [],
     integrityMismatches: [],
     providerFailures: [],
     budgetWithheld: [],
     generated: [],
     notices: [],
     needsReview: [],
+    unfilled: [],
+    malformedRows: [],
+    duplicateKeys: [],
     error: describeError(error)
   };
 }
+function deriveLocaleStatus(parts) {
+  const withheld = parts.integrityMismatches.length > 0 || parts.providerFailures.length > 0 || parts.budgetWithheld.length > 0;
+  if (!withheld) {
+    return "succeeded";
+  }
+  const accepted = parts.translated.length > 0 || parts.cacheHits.length > 0 || parts.generated.length > 0;
+  return accepted ? "partial" : "failed";
+}
 function partition(locales) {
-  const succeeded = locales.filter((s) => s.status === "succeeded").map((s) => s.locale);
-  const failed = locales.filter((s) => s.status === "failed").map((s) => s.locale);
-  return { succeeded, failed };
+  const namesWith = (status) => locales.filter((s) => s.status === status).map((s) => s.locale);
+  return {
+    succeeded: namesWith("succeeded"),
+    partial: namesWith("partial"),
+    failed: namesWith("failed")
+  };
 }
 
 // src/flow/batching.ts
@@ -4202,6 +4873,97 @@ function foldGenerationItem(item, result, adapter, accepted, withheld, providerF
 }
 
 // src/flow/locale-run.ts
+function partitionCacheHits(params, toTranslate) {
+  const cache = params.cache;
+  const hits = /* @__PURE__ */ new Map();
+  if (cache === void 0) {
+    return { hits, misses: toTranslate };
+  }
+  const misses = [];
+  for (const key of toTranslate) {
+    const source = params.source.entries.get(key);
+    if (source === void 0) {
+      continue;
+    }
+    const cached = lookupMemory(
+      cache.snapshot,
+      cache.fingerprint,
+      params.targetLocale,
+      contentHash(source)
+    );
+    if (cached !== void 0 && gateCandidateValue(source, cached, params.adapter).accepted) {
+      hits.set(key, { value: cached, source });
+    } else {
+      misses.push(key);
+    }
+  }
+  return { hits, misses };
+}
+function collectCacheAdditions(params, accepted, cacheHitKeys) {
+  if (params.cache === void 0) {
+    return [];
+  }
+  const additions = [];
+  for (const [key, entry] of accepted) {
+    if (!cacheHitKeys.has(key)) {
+      additions.push({ contentHash: contentHash(entry.source), value: entry.value });
+    }
+  }
+  return additions;
+}
+function groupMissesByContent(params, misses) {
+  const byHash = /* @__PURE__ */ new Map();
+  for (const key of misses) {
+    const source = params.source.entries.get(key);
+    if (source === void 0) {
+      continue;
+    }
+    const existing = byHash.get(contentHash(source));
+    if (existing === void 0) {
+      byHash.set(contentHash(source), { representative: key, duplicates: [] });
+    } else {
+      existing.duplicates.push(key);
+    }
+  }
+  return [...byHash.values()];
+}
+function fanOutContentDuplicates(params, groups, outcome) {
+  for (const group of groups) {
+    if (group.duplicates.length > 0) {
+      applyGroupOutcome(params, group, outcome);
+    }
+  }
+}
+function applyGroupOutcome(params, group, outcome) {
+  const acceptedRepresentative = outcome.accepted.get(group.representative);
+  if (acceptedRepresentative !== void 0) {
+    fanOutAccepted(params, group, acceptedRepresentative, outcome);
+    return;
+  }
+  withheldBucketFor(group.representative, outcome).push(...group.duplicates);
+}
+function fanOutAccepted(params, group, acceptedRepresentative, outcome) {
+  const flag = outcome.reviewFlags.get(group.representative);
+  for (const key of group.duplicates) {
+    const source = params.source.entries.get(key);
+    if (source === void 0) {
+      continue;
+    }
+    outcome.accepted.set(key, { value: acceptedRepresentative.value, source });
+    if (flag !== void 0) {
+      outcome.reviewFlags.set(key, flag);
+    }
+  }
+}
+function withheldBucketFor(representative, outcome) {
+  if (outcome.integrityMismatches.includes(representative)) {
+    return outcome.integrityMismatches;
+  }
+  if (outcome.budgetWithheld.includes(representative)) {
+    return outcome.budgetWithheld;
+  }
+  return outcome.providerFailures;
+}
 function buildRequest3(params, entries) {
   return {
     sourceLocale: params.sourceLocale,
@@ -4244,6 +5006,7 @@ async function runLocale(params) {
         orphaned,
         invalidIcuSource,
         translated: toTranslate,
+        cacheHits: [],
         generated: [],
         integrityMismatches: [],
         providerFailures: [],
@@ -4251,12 +5014,16 @@ async function runLocale(params) {
         pruned,
         notices: sdkNotices
       }),
-      lockEntries: {}
+      lockEntries: {},
+      cacheAdditions: []
     };
   }
-  const entries = toTranslate.map((key) => params.source.entries.get(key)).filter((entry) => entry !== void 0);
+  const partition2 = partitionCacheHits(params, toTranslate);
+  const cacheHitKeys = new Set(partition2.hits.keys());
+  const missGroups = groupMissesByContent(params, partition2.misses);
+  const entries = missGroups.map((group) => params.source.entries.get(group.representative)).filter((entry) => entry !== void 0);
   const startedStopped = params.budget.stopped;
-  const accepted = /* @__PURE__ */ new Map();
+  const accepted = new Map(partition2.hits);
   const integrityMismatches = [];
   const providerFailures = [];
   const budgetWithheld = [];
@@ -4271,6 +5038,13 @@ async function runLocale(params) {
     budgetWithheld,
     reviewFlags
   );
+  fanOutContentDuplicates(params, missGroups, {
+    accepted,
+    integrityMismatches,
+    providerFailures,
+    budgetWithheld,
+    reviewFlags
+  });
   const merged = new Map(target.entries);
   for (const key of pruned) {
     merged.delete(key);
@@ -4317,7 +5091,8 @@ async function runLocale(params) {
       unchanged: diff2.unchanged,
       orphaned,
       invalidIcuSource,
-      translated: [...accepted.keys()],
+      translated: [...accepted.keys()].filter((key) => !cacheHitKeys.has(key)),
+      cacheHits: [...cacheHitKeys].sort(),
       generated: generation.accepted.map((form) => form.targetKey).sort(),
       integrityMismatches: [...integrityMismatches, ...generation.withheld].sort(),
       providerFailures: [...providerFailures, ...generation.providerFailures].sort(),
@@ -4327,7 +5102,8 @@ async function runLocale(params) {
       needsReview: needsReviewFor(accepted.keys(), reviewFlags),
       ...localeUsage !== void 0 ? { usage: localeUsage } : {}
     }),
-    lockEntries: computeLockEntries(params, merged, withheld, generation.accepted)
+    lockEntries: computeLockEntries(params, merged, withheld, generation.accepted),
+    cacheAdditions: collectCacheAdditions(params, accepted, cacheHitKeys)
   };
 }
 var NO_GENERATION_RESULT = {
@@ -4372,18 +5148,22 @@ function pluralNoticeFor(params, merged) {
 function baseSummary(parts) {
   return {
     locale: parts.locale,
-    status: "succeeded",
+    status: deriveLocaleStatus(parts),
     translated: parts.translated,
     unchanged: parts.unchanged,
     orphaned: parts.orphaned,
     pruned: parts.pruned,
     invalidIcuSource: parts.invalidIcuSource,
+    cacheHits: parts.cacheHits,
     integrityMismatches: parts.integrityMismatches,
     providerFailures: parts.providerFailures,
     budgetWithheld: parts.budgetWithheld,
     generated: parts.generated,
     notices: parts.notices,
     needsReview: parts.needsReview ?? [],
+    unfilled: [],
+    malformedRows: [],
+    duplicateKeys: [],
     ...parts.usage !== void 0 ? { usage: parts.usage } : {}
   };
 }
@@ -4401,7 +5181,16 @@ async function translateAndCheck(provider, params, entries, accepted, integrityM
   const notices = [];
   const usage = createUsageAccumulator();
   let tripped = false;
-  for (const batch of chunk(entries, params.maxBatchSize)) {
+  const batches = chunk(entries, params.maxBatchSize);
+  let batchIndex = 0;
+  for (const batch of batches) {
+    batchIndex += 1;
+    params.onProgress?.({
+      type: "sub-batch",
+      locale: params.targetLocale,
+      batchIndex,
+      totalBatches: batches.length
+    });
     if (params.budget.stopped) {
       for (const entry of batch) {
         budgetWithheld.push(entry.key);
@@ -4431,10 +5220,16 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
   try {
     result = await provider.translateBatch(buildRequest3(params, batch));
   } catch (error) {
-    for (const entry of batch) {
-      providerFailures.push(entry.key);
-    }
-    return { notices: [subBatchFailedNotice(batch.length, error)], usage: void 0 };
+    return handleSubBatchFailure(
+      error,
+      provider,
+      params,
+      batch,
+      accepted,
+      integrityMismatches,
+      providerFailures,
+      reviewFlags
+    );
   }
   for (const entry of batch) {
     foldEntryResult(entry, result, params.adapter, accepted, integrityMismatches, providerFailures);
@@ -4446,6 +5241,44 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
   }
   return { notices: readNotices(result), usage: result.usage };
 }
+function isOutputTruncated(error) {
+  return error instanceof ProviderError && error.code === "OUTPUT_TRUNCATED";
+}
+async function handleSubBatchFailure(error, provider, params, batch, accepted, integrityMismatches, providerFailures, reviewFlags) {
+  if (isOutputTruncated(error) && batch.length > 1) {
+    return retryTruncatedSplit(
+      provider,
+      params,
+      batch,
+      accepted,
+      integrityMismatches,
+      providerFailures,
+      reviewFlags
+    );
+  }
+  for (const entry of batch) {
+    providerFailures.push(entry.key);
+  }
+  return { notices: [subBatchFailedNotice(batch.length, error)], usage: void 0 };
+}
+async function retryTruncatedSplit(provider, params, batch, accepted, integrityMismatches, providerFailures, reviewFlags) {
+  const notices = [];
+  let usage;
+  for (const half of chunk(batch, Math.ceil(batch.length / 2))) {
+    const sub = await runSubBatch(
+      provider,
+      params,
+      half,
+      accepted,
+      integrityMismatches,
+      providerFailures,
+      reviewFlags
+    );
+    notices.push(...sub.notices);
+    usage = combineUsage(usage, sub.usage);
+  }
+  return { notices, usage };
+}
 function foldEntryResult(entry, result, adapter, accepted, integrityMismatches, providerFailures) {
   const value = result.values.get(entry.key);
   if (value === void 0) {
@@ -4503,6 +5336,26 @@ async function recordRunStatus(cwd, dryRun, summary, fs) {
   } catch {
   }
 }
+async function createRunCacheState(input, config, cwd, dryRun, fs) {
+  if (dryRun || input.cache === false) {
+    return void 0;
+  }
+  return {
+    memory: await readTranslationMemory(cacheFilePath(cwd), fs),
+    fingerprint: computeFingerprint(config),
+    additions: /* @__PURE__ */ new Map()
+  };
+}
+async function recordCacheAdditions(cwd, cache, fs) {
+  if (cache === void 0 || cache.additions.size === 0) {
+    return;
+  }
+  try {
+    const merged = applyAdditions(cache.memory, cache.fingerprint, cache.additions);
+    await writeTranslationMemory(cacheFilePath(cwd), merged, fs);
+  } catch {
+  }
+}
 function buildLocaleRunParams(context, targetLocale, baseline) {
   return {
     source: context.source.resource,
@@ -4521,7 +5374,9 @@ function buildLocaleRunParams(context, targetLocale, baseline) {
     generatePlurals: context.generatePlurals,
     maxBatchSize: context.maxBatchSize,
     fs: context.fs,
-    budget: context.budget
+    budget: context.budget,
+    ...context.cache !== void 0 ? { cache: { snapshot: context.cache.memory, fingerprint: context.cache.fingerprint } } : {},
+    ...context.onProgress !== void 0 ? { onProgress: context.onProgress } : {}
   };
 }
 async function runDryLocale(context, targetLocale, lock) {
@@ -4529,16 +5384,29 @@ async function runDryLocale(context, targetLocale, lock) {
   return (await runLocale(params)).summary;
 }
 async function runLiveLocale(context, targetLocale) {
-  return withLocaleWriteLock(context.cwd, targetLocale, context.fs, async () => {
-    const lock = await readLockFile(lockFilePath(context.cwd), context.fs);
-    const params = buildLocaleRunParams(context, targetLocale, baselineFor(lock, targetLocale));
-    const result = await runLocale(params);
-    await updateLockFileLocale(context.cwd, context.fs, targetLocale, {
-      mode: "replace",
-      entries: result.lockEntries
-    });
-    return result.summary;
-  });
+  const lockOptions = {
+    ...context.onLockWait !== void 0 ? { onWait: context.onLockWait } : {},
+    ...context.lockAcquireTimeoutMs !== void 0 ? { acquireTimeoutMs: context.lockAcquireTimeoutMs } : {}
+  };
+  return withLocaleWriteLock(
+    context.cwd,
+    targetLocale,
+    context.fs,
+    async () => {
+      const lock = await readLockFile(lockFilePath(context.cwd), context.fs);
+      const params = buildLocaleRunParams(context, targetLocale, baselineFor(lock, targetLocale));
+      const result = await runLocale(params);
+      await updateLockFileLocale(context.cwd, context.fs, targetLocale, {
+        mode: "replace",
+        entries: result.lockEntries
+      });
+      if (context.cache !== void 0 && result.cacheAdditions.length > 0) {
+        context.cache.additions.set(targetLocale, additionsToRecord(result.cacheAdditions));
+      }
+      return result.summary;
+    },
+    lockOptions
+  );
 }
 async function runOneLocale(targetLocale, run) {
   try {
@@ -4550,27 +5418,88 @@ async function runOneLocale(targetLocale, run) {
     return failureSummary(targetLocale, error);
   }
 }
-async function runAllLocalesDry(context, targetLocales) {
+async function runLocaleAt(context, targetLocales, localeIndex, runOne, results) {
+  const targetLocale = targetLocales[localeIndex];
+  if (targetLocale === void 0) {
+    return;
+  }
+  context.onProgress?.({
+    type: "locale-started",
+    locale: targetLocale,
+    localeIndex,
+    totalLocales: targetLocales.length
+  });
+  const summary = await runOneLocale(targetLocale, () => runOne(targetLocale));
+  results[localeIndex] = summary;
+  context.onProgress?.({
+    type: "locale-finished",
+    locale: targetLocale,
+    translated: summary.translated.length
+  });
+}
+async function runLocalesWithProgress(context, targetLocales, runOne, concurrency) {
+  const totalLocales = targetLocales.length;
+  const results = new Array(totalLocales);
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < totalLocales) {
+      const localeIndex = nextIndex;
+      nextIndex += 1;
+      await runLocaleAt(context, targetLocales, localeIndex, runOne, results);
+    }
+  }
+  const workerCount = Math.min(concurrency, totalLocales);
+  const workers = [];
+  for (let index = 0; index < workerCount; index += 1) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results.filter((summary) => summary !== void 0);
+}
+async function runAllLocalesDry(context, targetLocales, concurrency) {
   const lock = await readLockFile(lockFilePath(context.cwd), context.fs);
-  const summaries = [];
-  for (const targetLocale of targetLocales) {
-    summaries.push(
-      await runOneLocale(targetLocale, () => runDryLocale(context, targetLocale, lock))
+  return runLocalesWithProgress(
+    context,
+    targetLocales,
+    (targetLocale) => runDryLocale(context, targetLocale, lock),
+    concurrency
+  );
+}
+async function runAllLocalesLive(context, targetLocales, concurrency) {
+  return runLocalesWithProgress(
+    context,
+    targetLocales,
+    (targetLocale) => runLiveLocale(context, targetLocale),
+    concurrency
+  );
+}
+function resolveConcurrency(value) {
+  if (value === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value < 1) {
+    throw new SdkError(
+      "CONCURRENCY_INVALID",
+      `The concurrency option must be an integer of at least 1, got ${value}.`
     );
   }
-  return summaries;
+  return value;
 }
-async function runAllLocalesLive(context, targetLocales) {
-  const summaries = [];
-  for (const targetLocale of targetLocales) {
-    summaries.push(await runOneLocale(targetLocale, () => runLiveLocale(context, targetLocale)));
+function resolveRunConcurrency(value, dryRun, config) {
+  const concurrency = resolveConcurrency(value);
+  if (!dryRun && concurrency > 1 && config.maxTokens !== void 0) {
+    throw new SdkError(
+      "CONCURRENCY_BUDGET_CONFLICT",
+      "A token budget (maxTokens) and concurrency greater than 1 cannot be combined on a live run: concurrent locales would overshoot the budget nondeterministically. Set concurrency to 1, remove maxTokens, or use --dry-run."
+    );
   }
-  return summaries;
+  return concurrency;
 }
 async function translate2(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const dryRun = input.dryRun ?? false;
+  const concurrency = resolveRunConcurrency(input.concurrency, dryRun, config);
   const prune = input.prune ?? config.prune ?? false;
   const generatePlurals = input.generatePlurals ?? config.generatePlurals ?? false;
   const maxBatchSize = config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
@@ -4582,6 +5511,7 @@ async function translate2(input, deps = {}) {
   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);
+  const cache = await createRunCacheState(input, config, cwd, dryRun, fs);
   const context = {
     source,
     adapter,
@@ -4592,10 +5522,15 @@ async function translate2(input, deps = {}) {
     generatePlurals,
     maxBatchSize,
     fs,
-    budget
+    budget,
+    cache,
+    ...input.onLockWait !== void 0 ? { onLockWait: input.onLockWait } : {},
+    ...input.onProgress !== void 0 ? { onProgress: input.onProgress } : {},
+    ...input.lockAcquireTimeoutMs !== void 0 ? { lockAcquireTimeoutMs: input.lockAcquireTimeoutMs } : {}
   };
-  const summaries = dryRun ? await runAllLocalesDry(context, config.targetLocales) : await runAllLocalesLive(context, config.targetLocales);
-  const { succeeded, failed } = partition(summaries);
+  const summaries = dryRun ? await runAllLocalesDry(context, config.targetLocales, concurrency) : await runAllLocalesLive(context, config.targetLocales, concurrency);
+  input.onProgress?.({ type: "run-finished", localesCompleted: summaries.length });
+  const { succeeded, partial, failed } = partition(summaries);
   const usage = summaries.reduce(
     (total, summary2) => combineUsage(total, summary2.usage),
     void 0
@@ -4605,10 +5540,12 @@ async function translate2(input, deps = {}) {
     dryRun,
     locales: summaries,
     succeeded,
+    partial,
     failed,
     ...usage !== void 0 ? { usage } : {},
     ...budgetSummary !== void 0 ? { budget: budgetSummary } : {}
   };
+  await recordCacheAdditions(cwd, cache, fs);
   await recordRunStatus(cwd, dryRun, summary, fs);
   return summary;
 }
@@ -4624,8 +5561,12 @@ var INSTRUCTIONS_LINES = [
   "How to use this workbook",
   "",
   "1. There is one sheet per language. Open the sheet named for the language you are translating.",
+  "   Do not rename, delete, or reorder the language tabs. verbatra matches each tab to a language by",
+  "   its exact name; a renamed or missing tab is reported and its translations are not imported.",
   "2. Fill ONLY the 'Translation' column. Leave every other column unchanged.",
-  "3. An empty 'Translation' cell means 'not translated yet'. It is skipped, never written as an empty string.",
+  "3. An empty 'Translation' cell means 'not translated yet'. It is skipped, never written as an empty",
+  "   string. A cell that contains only spaces is treated the same as an empty cell.",
+  "   To deliberately clear an existing value (set it to empty), type exactly [[CLEAR]] in the cell.",
   "4. Keep placeholders exactly as they appear. A token such as {name} or {count} must stay verbatim,",
   "   in your translation, with the same spelling. Do not translate or remove it.",
   "5. For ICU messages (for example {count, plural, one {# item} other {# items}}), keep the ICU",
@@ -4790,6 +5731,26 @@ function buildInstructionsSheet(workbook) {
   }
   sheet.getRow(1).font = { bold: true };
 }
+var WORKBOOK_PROTECTION_XML = '<workbookProtection lockStructure="1" lockWindows="0"/>';
+function spliceWorkbookProtection(xml) {
+  const anchor = xml.includes("<bookViews") ? "<bookViews" : "<sheets";
+  return xml.replace(anchor, `${WORKBOOK_PROTECTION_XML}${anchor}`);
+}
+async function protectWorkbookStructure(bytes) {
+  let zip;
+  try {
+    zip = await JSZip.loadAsync(bytes);
+  } catch {
+    throw new ExchangeError("WORKBOOK_INVALID", "The workbook could not be serialized.");
+  }
+  const workbookPart = zip.file("xl/workbook.xml");
+  if (workbookPart === null) {
+    return bytes;
+  }
+  const xml = await workbookPart.async("string");
+  zip.file("xl/workbook.xml", spliceWorkbookProtection(xml));
+  return zip.generateAsync({ type: "uint8array", compression: "DEFLATE" });
+}
 async function buildWorkbook(model) {
   assertNoWorksheetNameCollisions(model.sheets);
   const workbook = new ExcelJS.Workbook();
@@ -4797,13 +5758,15 @@ async function buildWorkbook(model) {
   for (const sheet of model.sheets) {
     await buildDataSheet(workbook, sheet);
   }
+  let serialized;
   try {
     const buffer = await workbook.xlsx.writeBuffer();
-    const view = buffer;
-    return Uint8Array.prototype.slice.call(view);
+    serialized = buffer;
   } catch {
     throw new ExchangeError("WORKBOOK_INVALID", "The workbook could not be serialized.");
   }
+  const protectedBytes = await protectWorkbookStructure(serialized);
+  return Uint8Array.prototype.slice.call(protectedBytes);
 }
 var DEFAULT_WORKBOOK_LIMITS = {
   maxDecompressedBytes: 64 * 1024 * 1024,
@@ -4923,26 +5886,24 @@ function assertHeader(sheet) {
     );
   }
 }
-function parseRow(sheet, row) {
+var MALFORMED_ROW_COLUMN = "Status";
+function parseRow(row) {
   const candidate = {
     key: cellString(row.getCell(COLUMN.key)),
     source: cellString(row.getCell(COLUMN.source)),
     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)).trim(),
     context: cellString(row.getCell(COLUMN.context)),
     reviewStatus: cellString(row.getCell(COLUMN.reviewStatus)),
     reviewReasons: cellString(row.getCell(COLUMN.reviewReasons))
   };
   const result = rowSchema.safeParse(candidate);
   if (!result.success) {
-    throw new ExchangeError(
-      "WORKBOOK_INVALID",
-      `The sheet "${sheet.name}" has a row with a missing key or an unrecognized status.`
-    );
+    return { ok: false, column: MALFORMED_ROW_COLUMN };
   }
-  return result.data;
+  return { ok: true, row: result.data };
 }
 function readDataSheet(sheet, limits) {
   assertHeader(sheet);
@@ -4953,6 +5914,9 @@ function readDataSheet(sheet, limits) {
     );
   }
   const rows = [];
+  const malformed = [];
+  const duplicates = [];
+  const seenKeys = /* @__PURE__ */ new Set();
   for (let rowNumber = HEADER_ROW + 1; rowNumber <= sheet.rowCount; rowNumber += 1) {
     const row = sheet.getRow(rowNumber);
     if (row.cellCount > limits.maxCellsPerRow) {
@@ -4964,9 +5928,19 @@ function readDataSheet(sheet, limits) {
     if (cellString(row.getCell(COLUMN.key)) === "") {
       continue;
     }
-    rows.push(parseRow(sheet, row));
+    const outcome = parseRow(row);
+    if (!outcome.ok) {
+      malformed.push({ locale: sheet.name, row: rowNumber, column: outcome.column });
+      continue;
+    }
+    if (seenKeys.has(outcome.row.key)) {
+      duplicates.push({ locale: sheet.name, key: outcome.row.key, row: rowNumber });
+      continue;
+    }
+    seenKeys.add(outcome.row.key);
+    rows.push(outcome.row);
   }
-  return { locale: sheet.name, rows };
+  return { sheet: { locale: sheet.name, rows }, malformed, duplicates };
 }
 async function loadWorkbook(bytes) {
   const workbook = new ExcelJS.Workbook();
@@ -4989,13 +5963,18 @@ async function readWorkbook(bytes, options = {}) {
     );
   }
   const sheets = [];
+  const malformedRows = [];
+  const duplicateKeys = [];
   for (const sheet of workbook.worksheets) {
     if (sheet.name === INSTRUCTIONS_SHEET_NAME) {
       continue;
     }
-    sheets.push(readDataSheet(sheet, limits));
+    const read = readDataSheet(sheet, limits);
+    sheets.push(read.sheet);
+    malformedRows.push(...read.malformed);
+    duplicateKeys.push(...read.duplicates);
   }
-  return { sheets };
+  return { sheets, malformedRows, duplicateKeys };
 }
 
 // src/flow/workbook/export-workbook.ts
@@ -5096,6 +6075,7 @@ async function exportWorkbook(input, deps = {}) {
 }
 
 // src/flow/workbook/import-locale.ts
+var CLEAR_SENTINEL = "[[CLEAR]]";
 var UnknownKeyError = class extends Error {
   key;
   constructor(key) {
@@ -5124,9 +6104,20 @@ function trackBlankDrift(row, params, buckets) {
     buckets.blankDrifted.add(row.key);
   }
 }
+function classifyClear(row, sourceEntry, buckets) {
+  if (contentHash(sourceEntry) !== row.sourceHash) {
+    buckets.mismatches.push(row.key);
+    buckets.withheld.add(row.key);
+    return;
+  }
+  buckets.accepted.set(row.key, { value: "", source: sourceEntry });
+}
 function classifyRows(params, buckets) {
   for (const row of params.sheet.rows) {
     if (row.translation === "") {
+      if (row.status === "changed") {
+        buckets.unfilled.push(row.key);
+      }
       trackBlankDrift(row, params, buckets);
       continue;
     }
@@ -5137,6 +6128,10 @@ function classifyRows(params, buckets) {
     if (sourceEntry === void 0) {
       continue;
     }
+    if (row.translation === CLEAR_SENTINEL) {
+      classifyClear(row, sourceEntry, buckets);
+      continue;
+    }
     const reason = judge(row, sourceEntry, params.adapter);
     if (reason === void 0) {
       buckets.accepted.set(row.key, { value: row.translation, source: sourceEntry });
@@ -5158,25 +6153,39 @@ function importLocale(params) {
     accepted: /* @__PURE__ */ new Map(),
     mismatches: [],
     withheld: /* @__PURE__ */ new Set(),
-    blankDrifted: /* @__PURE__ */ new Set()
+    blankDrifted: /* @__PURE__ */ new Set(),
+    unfilled: []
   };
   classifyRows(params, buckets);
   const rowKeys = new Set(params.sheet.rows.map((row) => row.key));
   const invalidIcuSource = [...new Set(params.sourceInvalidIcuKeys)].filter((key) => rowKeys.has(key)).sort();
+  const translated = [...buckets.accepted.keys()].sort();
+  const integrityMismatches = [...buckets.mismatches].sort();
   const summary = {
     locale: params.sheet.locale,
-    status: "succeeded",
-    translated: [...buckets.accepted.keys()].sort(),
+    status: deriveLocaleStatus({
+      translated,
+      cacheHits: [],
+      generated: [],
+      integrityMismatches,
+      providerFailures: [],
+      budgetWithheld: []
+    }),
+    translated,
     unchanged: diff2.unchanged,
     orphaned: diff2.orphaned,
     pruned: [],
     invalidIcuSource,
-    integrityMismatches: [...buckets.mismatches].sort(),
+    cacheHits: [],
+    integrityMismatches,
     providerFailures: [],
     budgetWithheld: [],
     generated: [],
     notices: buckets.blankDrifted.size > 0 ? [blankRowBaselineNotice(buckets.blankDrifted.size)] : [],
-    needsReview: []
+    needsReview: [],
+    unfilled: [...new Set(buckets.unfilled)].sort(),
+    malformedRows: params.malformedRows,
+    duplicateKeys: params.duplicateKeys
   };
   return { summary, accepted: buckets.accepted, withheld: buckets.withheld };
 }
@@ -5203,6 +6212,19 @@ function mergeAccepted(target, accepted) {
   }
   return merged;
 }
+function sheetCacheAdditions(accepted) {
+  const record = {};
+  for (const [, { value, source }] of accepted) {
+    record[contentHash(source)] = value;
+  }
+  return record;
+}
+function collectSheetAdditions(byLocale, locale, additions) {
+  if (Object.keys(additions).length === 0) {
+    return;
+  }
+  byLocale.set(locale, { ...byLocale.get(locale), ...additions });
+}
 function computeLockEntries2(source, merged, baseline, accepted) {
   const entries = {};
   for (const key of merged.keys()) {
@@ -5219,11 +6241,20 @@ function computeLockEntries2(source, merged, baseline, accepted) {
   }
   return entries;
 }
+var MissingSheetError = class extends Error {
+  code = "WORKBOOK_SHEET_MISSING";
+  constructor(locale) {
+    super(
+      `The workbook has no sheet (tab) for the configured target locale "${locale}". The tab may have been renamed, deleted, or reordered out of the workbook.`
+    );
+    this.name = "MissingSheetError";
+  }
+};
 async function runSheet(ctx, sheet, lock) {
   if (!ctx.config.targetLocales.includes(sheet.locale)) {
     throw new SdkError(
       "CONFIG_INVALID",
-      `The workbook has a sheet for locale "${sheet.locale}", which is not a configured target locale.`
+      `The workbook has a sheet named "${sheet.locale}", which is not a configured target locale. It may be a renamed, added, or reordered tab; leave every language tab named exactly as exported.`
     );
   }
   const target = await readTarget(ctx.cwd, ctx.config, ctx.adapter, ctx.fs, sheet.locale);
@@ -5234,10 +6265,12 @@ async function runSheet(ctx, sheet, lock) {
     target,
     baseline,
     adapter: ctx.adapter,
-    sourceInvalidIcuKeys: ctx.sourceInvalidIcuKeys
+    sourceInvalidIcuKeys: ctx.sourceInvalidIcuKeys,
+    malformedRows: ctx.malformedRows.filter((problem) => problem.locale === sheet.locale).map((problem) => ({ row: problem.row, column: problem.column })),
+    duplicateKeys: ctx.duplicateKeys.filter((duplicate) => duplicate.locale === sheet.locale).map((duplicate) => ({ key: duplicate.key, row: duplicate.row }))
   });
   if (ctx.dryRun) {
-    return { summary, lockEntries: {} };
+    return { summary, lockEntries: {}, cacheAdditions: {} };
   }
   const merged = mergeAccepted(target, accepted);
   if (accepted.size > 0) {
@@ -5252,7 +6285,11 @@ async function runSheet(ctx, sheet, lock) {
       path
     );
   }
-  return { summary, lockEntries: computeLockEntries2(ctx.source, merged, baseline, accepted) };
+  return {
+    summary,
+    lockEntries: computeLockEntries2(ctx.source, merged, baseline, accepted),
+    cacheAdditions: sheetCacheAdditions(accepted)
+  };
 }
 async function importWorkbook(input, deps = {}) {
   const config = input.config;
@@ -5277,9 +6314,12 @@ async function importWorkbook(input, deps = {}) {
     fs,
     source: source.resource,
     sourceInvalidIcuKeys: source.invalidIcuKeys,
-    dryRun
+    dryRun,
+    malformedRows: data.malformedRows,
+    duplicateKeys: data.duplicateKeys
   };
   const summaries = [];
+  const cacheAdditions = /* @__PURE__ */ new Map();
   for (const sheet of data.sheets) {
     try {
       let summary;
@@ -5292,6 +6332,7 @@ async function importWorkbook(input, deps = {}) {
             mode: "replace",
             entries: result.lockEntries
           });
+          collectSheetAdditions(cacheAdditions, sheet.locale, result.cacheAdditions);
           return result.summary;
         });
       }
@@ -5300,8 +6341,17 @@ async function importWorkbook(input, deps = {}) {
       summaries.push(failureSummary(sheet.locale, error));
     }
   }
-  const { succeeded, failed } = partition(summaries);
-  return { dryRun, locales: summaries, succeeded, failed };
+  const presentLocales = new Set(data.sheets.map((sheet) => sheet.locale));
+  for (const locale of config.targetLocales) {
+    if (!presentLocales.has(locale)) {
+      summaries.push(failureSummary(locale, new MissingSheetError(locale)));
+    }
+  }
+  if (!dryRun) {
+    await feedTranslationMemory(cwd, fs, computeFingerprint(config), cacheAdditions);
+  }
+  const { succeeded, partial, failed } = partition(summaries);
+  return { dryRun, locales: summaries, succeeded, partial, failed };
 }
 
 // src/lock/load-lock-file.ts
@@ -5359,7 +6409,15 @@ async function watch(input, deps = {}) {
     );
   }
   const runTranslate = deps.runTranslate ?? defaultRunTranslate(deps);
-  const runInput = { config: input.config, cwd };
+  const runInput = {
+    config: input.config,
+    cwd,
+    ...input.onLockWait !== void 0 ? { onLockWait: input.onLockWait } : {},
+    ...input.onProgress !== void 0 ? { onProgress: input.onProgress } : {},
+    ...input.lockAcquireTimeoutMs !== void 0 ? { lockAcquireTimeoutMs: input.lockAcquireTimeoutMs } : {},
+    ...input.concurrency !== void 0 ? { concurrency: input.concurrency } : {},
+    ...input.cache !== void 0 ? { cache: input.cache } : {}
+  };
   let state = "idle";
   let pending = false;
   let stopped = false;
@@ -5426,6 +6484,6 @@ async function watch(input, deps = {}) {
   return { stop };
 }
 
-export { DEFAULT_WORKBOOK_PATH, LOCK_FILE_NAME, SdkError, check, defineConfig, diff, diffLocaleSnapshots, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate2 as translate, verbatraConfigSchema, watch };
+export { CACHE_FILE_NAME, DEFAULT_WORKBOOK_PATH, LOCK_FILE_NAME, SdkError, check, defineConfig, diff, diffLocaleSnapshots, editEntry, exportWorkbook, importWorkbook, keyIntegrity, keyValue, loadConfig, loadConfigWithMeta, loadLockFile, lockState, readLocaleFileSnapshot, retranslateEntry, runStatus, scaffoldingMetadata, translate2 as translate, verbatraConfigSchema, watch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map