@verbatra/sdk 0.5.0-next.1 → 0.5.0-next.3

package/README.md

@@ -71,7 +71,7 @@ export default defineConfig({
 });
 ```
 
-`files.pattern` must contain the `{locale}` token, and `targetLocales` must not include `sourceLocale`; both are enforced when the config is validated. The supported `format` values are `i18next-json`, `vue-i18n-json`, `next-intl-json`, `ngx-translate-json`, `xliff`, `yaml`, and `arb`. The optional `glossary` (a term map) and `tone` (`"formal"`, `"informal"`, or `"neutral"`) refine the output. The optional `prune` boolean (off by default) opts in to removing orphaned keys (present in a target file but absent from the source) from the written target files and the lock; the `translate --prune` flag overrides it per run. The optional `generatePlurals` boolean (off by default) opts in to synthesizing the CLDR plural forms a richer target language requires but the source lacks (i18next-JSON projects translated by an LLM provider only; DeepL, non-i18next formats, and unknown languages fall back to the per-locale plural warning and never fail); a per-run `generatePlurals` override on `translate` takes precedence, and generated keys are reported separately from translated keys on the summary. OpenAI and Gemini take `{ model, maxOutputTokens }`; DeepL takes `{}` (with an optional `glossaryId`). API keys are never part of the config. Each provider reads its own environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`).
+`files.pattern` must contain the `{locale}` token, and `targetLocales` must not include `sourceLocale`; both are enforced when the config is validated. The supported `format` values are `i18next-json`, `vue-i18n-json`, `next-intl-json`, `ngx-translate-json`, `xliff`, `yaml`, and `arb`. The optional `glossary` (a term map) and `tone` (`"formal"`, `"informal"`, or `"neutral"`) refine the output. The optional `prune` boolean (off by default) opts in to removing orphaned keys (present in a target file but absent from the source) from the written target files and the lock; the `translate --prune` flag overrides it per run. The optional `generatePlurals` boolean (off by default) opts in to synthesizing the CLDR plural forms a richer target language requires but the source lacks (i18next-JSON projects translated by an LLM provider only; DeepL, non-i18next formats, and unknown languages fall back to the per-locale plural warning and never fail); a per-run `generatePlurals` override on `translate` takes precedence, and generated keys are reported separately from translated keys on the summary. OpenAI and Gemini take `{ model, maxOutputTokens }`; `openai-compatible` additionally takes a `baseUrl` (for a local or self-hosted server such as LM Studio, Ollama, or vLLM) and an optional `apiKeyEnvVar`; DeepL takes `{}` (with an optional `glossaryId`). API keys are never part of the config. Each provider reads its own environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPL_API_KEY`; `openai-compatible` resolves its key from `apiKeyEnvVar`, then `OPENAI_COMPATIBLE_API_KEY`, then falls back to a keyless placeholder).
 
 ## API reference
 

package/dist/index.cjs

@@ -503,16 +503,14 @@ function validateRequest(request) {
   return parsed.data;
 }
 function toIntegrityInputs(entries, values) {
-  return entries.map((entry) => {
+  const inputs = [];
+  for (const entry of entries) {
     const translatedValue = values.get(entry.key);
-    if (translatedValue === void 0) {
-      throw new ProviderError(
-        "INVALID_RESPONSE",
-        "The provider response is missing one or more keys."
-      );
+    if (translatedValue !== void 0) {
+      inputs.push({ key: entry.key, sourceValue: entry.value, translatedValue });
     }
-    return { key: entry.key, sourceValue: entry.value, translatedValue };
-  });
+  }
+  return inputs;
 }
 function toItem(entry) {
   return {
@@ -544,25 +542,29 @@ function deriveJsonSchema(schema) {
   }
   return result;
 }
-function reconcile(translations, requestedKeys) {
-  const requested = new Set(requestedKeys);
-  const values = /* @__PURE__ */ new Map();
+function partitionTranslations(translations, requested) {
+  const firstSeen = /* @__PURE__ */ new Map();
+  const duplicated = /* @__PURE__ */ new Set();
   for (const { key, value } of translations) {
-    if (!requested.has(key) || values.has(key)) {
-      throw new ProviderError(
-        "INVALID_RESPONSE",
-        "The provider returned an unexpected or duplicate key."
-      );
+    if (!requested.has(key)) {
+      throw new ProviderError("INVALID_RESPONSE", "The provider returned an unexpected key.");
     }
-    values.set(key, value);
+    if (firstSeen.has(key)) {
+      duplicated.add(key);
+      continue;
+    }
+    firstSeen.set(key, value);
   }
-  if (values.size !== requested.size) {
-    throw new ProviderError(
-      "INVALID_RESPONSE",
-      "The provider response is missing one or more keys."
-    );
+  return { firstSeen, duplicated };
+}
+function reconcile(translations, requestedKeys) {
+  const requested = new Set(requestedKeys);
+  const { firstSeen, duplicated } = partitionTranslations(translations, requested);
+  const missingKeys = requestedKeys.filter((key) => duplicated.has(key) || !firstSeen.has(key));
+  for (const key of duplicated) {
+    firstSeen.delete(key);
   }
-  return values;
+  return { accepted: firstSeen, missingKeys };
 }
 function reconcileResult(raw, requestedKeys) {
   const parsed = translationsResultSchema.safeParse(raw);
@@ -574,22 +576,54 @@ function reconcileResult(raw, requestedKeys) {
   }
   return reconcile(parsed.data.translations, requestedKeys);
 }
+var MAX_REPAIR_ROUNDS = 1;
 async function runLlmTranslation(request, mechanism) {
   const data = validateRequest(request);
+  const signal = request.signal;
+  const first = await requestTranslations(mechanism, data, signal);
+  const values = first.outcome.accepted;
+  let usage = first.completion.usage;
+  let toRepair = entriesFor(data.entries, first.outcome.missingKeys);
+  for (let round = 0; round < MAX_REPAIR_ROUNDS && toRepair.length > 0; round += 1) {
+    const repair = await requestTranslations(mechanism, { ...data, entries: toRepair }, signal);
+    for (const [key, value] of repair.outcome.accepted) {
+      values.set(key, value);
+    }
+    usage = mergeUsage(usage, repair.completion.usage);
+    toRepair = entriesFor(data.entries, repair.outcome.missingKeys);
+  }
+  const integrity = checkBatchIntegrity(
+    toIntegrityInputs(data.entries, values),
+    request.extractPlaceholders,
+    request.comparePlaceholders
+  );
+  return usage === void 0 ? { values, integrity, notices: [] } : { values, integrity, usage, notices: [] };
+}
+async function requestTranslations(mechanism, data, signal) {
   const payloadJson = JSON.stringify(buildDataPayload(data));
   const requestedKeys = data.entries.map((entry) => entry.key);
   const completion = await mechanism.translate({
     payloadJson,
     requestedKeys,
-    ...request.signal !== void 0 ? { signal: request.signal } : {}
+    ...signal !== void 0 ? { signal } : {}
   });
-  const values = reconcileResult(completion.raw, requestedKeys);
-  const integrity = checkBatchIntegrity(
-    toIntegrityInputs(data.entries, values),
-    request.extractPlaceholders,
-    request.comparePlaceholders
-  );
-  return completion.usage === void 0 ? { values, integrity } : { values, integrity, usage: completion.usage };
+  return { completion, outcome: reconcileResult(completion.raw, requestedKeys) };
+}
+function entriesFor(entries, keys) {
+  const wanted = new Set(keys);
+  return entries.filter((entry) => wanted.has(entry.key));
+}
+function mergeUsage(first, second) {
+  if (first === void 0) {
+    return second;
+  }
+  if (second === void 0) {
+    return first;
+  }
+  return {
+    inputTokens: first.inputTokens + second.inputTokens,
+    outputTokens: first.outputTokens + second.outputTokens
+  };
 }
 var OUTPUT_TRUNCATED_MESSAGE = "The provider stopped because the output-token limit was reached. Reduce the batch size or raise the configured max output tokens.";
 function assertNotTruncated(truncated) {
@@ -773,6 +807,50 @@ function createDefaultClient2() {
   };
   return { client, freeAccount };
 }
+var DEEPL_MAX_TEXTS_PER_REQUEST = 50;
+var DEEPL_MAX_PAYLOAD_BYTES = 128 * 1024;
+var DEEPL_PAYLOAD_OVERHEAD_RESERVE_BYTES = 4 * 1024;
+var DEEPL_MAX_TEXT_PAYLOAD_BYTES = DEEPL_MAX_PAYLOAD_BYTES - DEEPL_PAYLOAD_OVERHEAD_RESERVE_BYTES;
+function estimateWireBytes(text) {
+  return encodeURIComponent(text).length;
+}
+function chunkTextsForDeepL(texts) {
+  const chunks = [];
+  let current = [];
+  let currentBytes = 0;
+  for (const text of texts) {
+    const textBytes = estimateWireBytes(text);
+    const startsNewChunk = current.length > 0 && (current.length >= DEEPL_MAX_TEXTS_PER_REQUEST || currentBytes + textBytes > DEEPL_MAX_TEXT_PAYLOAD_BYTES);
+    if (startsNewChunk) {
+      chunks.push(current);
+      current = [];
+      currentBytes = 0;
+    }
+    current.push(text);
+    currentBytes += textBytes;
+  }
+  if (current.length > 0) {
+    chunks.push(current);
+  }
+  return chunks;
+}
+var DEPRECATED_BARE_TARGET_CODES = /* @__PURE__ */ new Set(["en", "pt"]);
+function assertValidDeepLSourceLocale(locale) {
+  if (locale.includes("-")) {
+    throw new ProviderError(
+      "INVALID_REQUEST",
+      `DeepL does not accept a regional or script source locale code: "${locale}". Only the base language code is valid as a DeepL source (for example, use "en" instead of "en-US").`
+    );
+  }
+}
+function assertValidDeepLTargetLocale(locale) {
+  if (DEPRECATED_BARE_TARGET_CODES.has(locale.toLowerCase())) {
+    throw new ProviderError(
+      "INVALID_REQUEST",
+      `DeepL requires a disambiguated target locale code instead of "${locale}" (for example, "en-GB" or "en-US" for English, "pt-PT" or "pt-BR" for Portuguese).`
+    );
+  }
+}
 var PLACEHOLDER_UNSUPPORTED_MESSAGE = "Some entries contain placeholders or ICU syntax that DeepL cannot preserve; they were left untranslated. Use an LLM provider to translate placeholder-bearing strings.";
 function partitionByPlaceholders(entries) {
   const protectable = [];
@@ -837,7 +915,10 @@ function createDeepLProvider(config, deps = {}) {
   return {
     id: PROVIDER_ID2,
     kind: "machine-translation",
-    supportsGlossary: true,
+    // Honest capability signal: DeepL only ever applies a pre-created native glossary id, never a
+    // generic term map (see buildTranslateOptions). Without one configured, a supplied term map is
+    // silently ignored and surfaces only as a GLOSSARY_IGNORED notice.
+    supportsGlossary: validConfig.glossaryId !== void 0,
     translateBatch: (request) => translate(bundle, validConfig, request)
   };
 }
@@ -849,6 +930,8 @@ function resolveClient(deps) {
 }
 async function translate(bundle, config, request) {
   const data = validateRequest(request);
+  assertValidDeepLSourceLocale(data.sourceLocale);
+  assertValidDeepLTargetLocale(data.targetLocale);
   const { protectable, unprotectable } = partitionByPlaceholders(data.entries);
   const genericGlossarySupplied = request.glossary !== void 0 && Object.keys(request.glossary).length > 0;
   const { options, notices } = buildTranslateOptions({
@@ -876,7 +959,7 @@ async function translateProtectable(client, data, protectable, options, extract,
     return { values: /* @__PURE__ */ new Map(), integrity: /* @__PURE__ */ new Map() };
   }
   const texts = protectable.map((entry) => entry.value);
-  const results = await callClient2(
+  const results = await callClientChunked(
     client,
     texts,
     data.sourceLocale,
@@ -894,6 +977,14 @@ function callClient2(client, texts, sourceLang, targetLang, options, signal) {
     signal
   );
 }
+async function callClientChunked(client, texts, sourceLang, targetLang, options, signal) {
+  const results = [];
+  for (const chunk2 of chunkTextsForDeepL(texts)) {
+    const chunkResults = await callClient2(client, chunk2, sourceLang, targetLang, options, signal);
+    results.push(...chunkResults);
+  }
+  return results;
+}
 var geminiConfigSchema = zod.z.object({
   model: zod.z.string().min(1),
   maxOutputTokens: zod.z.number().int().positive()
@@ -1141,16 +1232,19 @@ function buildResponseFormat(mode) {
     }
   };
 }
-function buildOpenAiRequest(config, payloadJson, mode = "strict-schema") {
-  return {
-    model: config.model,
-    max_completion_tokens: config.maxOutputTokens,
+function buildOpenAiRequest(config, payloadJson, mode = "strict-schema", tokenLimitField = "max_completion_tokens") {
+  const base = {
     messages: [
       { role: "system", content: OPENAI_SYSTEM_RULES },
       { role: "user", content: payloadJson }
     ],
+    model: config.model,
     response_format: buildResponseFormat(mode)
   };
+  if (tokenLimitField === "max_tokens") {
+    return { ...base, max_tokens: config.maxOutputTokens };
+  }
+  return { ...base, max_completion_tokens: config.maxOutputTokens };
 }
 function advanceStringScan(char, escaped) {
   if (escaped) {
@@ -1321,7 +1415,7 @@ function createOpenAiCompatibleProvider(config, deps = {}) {
 function createMechanism4(client, config) {
   return {
     translate: async ({ payloadJson, signal }) => {
-      const body = buildOpenAiRequest(config, payloadJson, "strict-schema");
+      const body = buildOpenAiRequest(config, payloadJson, "strict-schema", "max_tokens");
       const completion = await callClient5(client, body, signal);
       return extractOpenAiResult(completion, true);
     }
@@ -1362,6 +1456,17 @@ function buildProvider(config) {
 
 // src/config/schema.ts
 var DEFAULT_MAX_BATCH_SIZE = 50;
+function findCaseInsensitiveDuplicate(locales) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const locale of locales) {
+    const key = locale.toLowerCase();
+    if (seen.has(key)) {
+      return locale;
+    }
+    seen.add(key);
+  }
+  return void 0;
+}
 var verbatraConfigSchema = zod.z.strictObject({
   sourceLocale: zod.z.string().min(1),
   targetLocales: zod.z.array(zod.z.string().min(1)).min(1),
@@ -1403,6 +1508,14 @@ var verbatraConfigSchema = zod.z.strictObject({
 }).refine((config) => !config.targetLocales.includes(config.sourceLocale), {
   message: "targetLocales must not include the source locale",
   path: ["targetLocales"]
+}).refine((config) => findCaseInsensitiveDuplicate(config.targetLocales) === void 0, {
+  error: (issue) => {
+    const duplicate = findCaseInsensitiveDuplicate(
+      issue.input.targetLocales
+    );
+    return `targetLocales must not contain case-insensitively duplicate locales: "${duplicate}"`;
+  },
+  path: ["targetLocales"]
 }).refine((config) => config.files.pattern.includes(LOCALE_TOKEN), {
   message: `files.pattern must contain the ${LOCALE_TOKEN} token`,
   path: ["files", "pattern"]
@@ -1922,6 +2035,9 @@ async function atomicWriteFile(path, data, ops = nodeOps) {
     throw error;
   }
 }
+function stripLeadingBom(content) {
+  return content.charCodeAt(0) === 65279 ? content.slice(1) : content;
+}
 async function readBoundedUtf82(handle, size) {
   const buffer = Buffer.allocUnsafe(size);
   let offset = 0;
@@ -1932,7 +2048,7 @@ async function readBoundedUtf82(handle, size) {
     }
     offset += bytesRead;
   }
-  return buffer.toString("utf8", 0, offset);
+  return stripLeadingBom(buffer.toString("utf8", 0, offset));
 }
 async function readBounded2(filePath) {
   const handle = await promises.open(filePath, "r");
@@ -2115,11 +2231,24 @@ function unflattenEntries(entries) {
   }
   return root;
 }
-function toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTree) {
+function mergeDescriptions(entries, content, deriveDescriptions) {
+  if (!deriveDescriptions) {
+    return;
+  }
+  for (const [key, description] of deriveDescriptions(content)) {
+    const entry = entries.get(key);
+    if (entry !== void 0) {
+      entries.set(key, { ...entry, description });
+    }
+  }
+}
+function toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTree, deriveDescriptions) {
   try {
     const tree = parse3(content);
     validateTree?.(tree);
-    return flattenTree(tree, namespace, deriveEntry, keyMode);
+    const entries = flattenTree(tree, namespace, deriveEntry, keyMode);
+    mergeDescriptions(entries, content, deriveDescriptions);
+    return entries;
   } catch (error) {
     rethrowStructured(error, "The file could not be parsed.");
   }
@@ -2138,6 +2267,7 @@ function createTreeFileAdapter(options) {
     validateTree,
     buildWriteTree,
     comparePlaceholders,
+    deriveDescriptions,
     keyMode = "literal-leaf"
   } = options;
   return {
@@ -2149,7 +2279,15 @@ function createTreeFileAdapter(options) {
     async read(filePath, locale) {
       const content = await readFileContent(filePath);
       const namespace = namespaceOf(filePath);
-      const entries = toEntries(content, namespace, parse3, deriveEntry, keyMode, validateTree);
+      const entries = toEntries(
+        content,
+        namespace,
+        parse3,
+        deriveEntry,
+        keyMode,
+        validateTree,
+        deriveDescriptions
+      );
       const resource = { locale, namespace, format, entries };
       const invalidIcuKeys = computeIcu(entries, computeInvalidIcuKeys);
       return { resource, invalidIcuKeys };
@@ -2190,6 +2328,31 @@ function stripArbMetadata(tree) {
 function originalKey(encoded) {
   return decodeKeyToSegments(encoded).join(".");
 }
+function messageKeyForMetadata(key) {
+  return isMetadataKey(key) && !key.startsWith("@@") ? key.slice(1) : null;
+}
+function descriptionOf(value) {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const description = value.description;
+  return typeof description === "string" ? description : void 0;
+}
+function extractArbDescriptions(content) {
+  const tree = parseArbObject(content);
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(tree)) {
+    const messageKey = messageKeyForMetadata(key);
+    if (messageKey === null) {
+      continue;
+    }
+    const description = descriptionOf(value);
+    if (description !== void 0) {
+      out.set(encodeSegment(messageKey), description);
+    }
+  }
+  return out;
+}
 function messagesFromEntries(entries) {
   const out = /* @__PURE__ */ new Map();
   for (const [key, entry] of entries) {
@@ -2246,7 +2409,8 @@ function createArbAdapter() {
     computeInvalidIcuKeys: icuInvalidKeys,
     validateMessage: icuIsValid,
     comparePlaceholders: compareIcuPlaceholders,
-    buildWriteTree: buildArbWriteTree
+    buildWriteTree: buildArbWriteTree,
+    deriveDescriptions: extractArbDescriptions
   });
 }
 function createJsonFileAdapter(options) {
@@ -2552,16 +2716,33 @@ function parseXml(content) {
   }
   return { doc, root };
 }
+function firstNoteText(parent) {
+  const note = childByName(parent, "note");
+  if (note === null) {
+    return void 0;
+  }
+  const text = (note.textContent ?? "").trim();
+  return text === "" ? void 0 : text;
+}
+function transUnitDescription(tu) {
+  return firstNoteText(tu);
+}
+function unitDescription(unit) {
+  const notes = childByName(unit, "notes");
+  return notes === null ? void 0 : firstNoteText(notes);
+}
 function walkXliff12(root) {
   const units = [];
   collectByTag(root, "trans-unit").forEach((tu, index) => {
     const source = childByName(tu, "source");
     if (source !== null) {
+      const description = transUnitDescription(tu);
       units.push({
         key: unitKey(tu, index),
         source,
         target: childByName(tu, "target"),
-        container: tu
+        container: tu,
+        ...description !== void 0 ? { description } : {}
       });
     }
   });
@@ -2571,12 +2752,19 @@ function walkXliff20(root) {
   const units = [];
   collectByTag(root, "unit").forEach((unit, index) => {
     const baseKey = unitKey(unit, index);
+    const description = unitDescription(unit);
     const segments = elementChildren(unit).filter((el) => el.localName === "segment");
     segments.forEach((segment, segIndex) => {
       const source = childByName(segment, "source");
       if (source !== null) {
         const key = segments.length > 1 ? `${baseKey}#${segIndex}` : baseKey;
-        units.push({ key, source, target: childByName(segment, "target"), container: segment });
+        units.push({
+          key,
+          source,
+          target: childByName(segment, "target"),
+          container: segment,
+          ...description !== void 0 ? { description } : {}
+        });
       }
     });
   });
@@ -2615,7 +2803,8 @@ function parseXliffEntries(content, namespace) {
       namespace,
       value,
       placeholders: extractXliffPlaceholders(value),
-      isPlural: false
+      isPlural: false,
+      ...unit.description !== void 0 ? { description: unit.description } : {}
     });
   }
   return out;
@@ -2975,15 +3164,8 @@ function subBatchFailedNotice(count, error) {
 }
 
 // src/flow/notices.ts
-function isNotice(value) {
-  return typeof value === "object" && value !== null && typeof value.code === "string" && typeof value.message === "string";
-}
 function readNotices(result) {
-  const candidate = result.notices;
-  if (!Array.isArray(candidate)) {
-    return [];
-  }
-  return candidate.filter(isNotice);
+  return result.notices ?? [];
 }
 
 // src/flow/plural-categories.ts
@@ -3187,20 +3369,26 @@ async function runGenerationSubBatch(context, batch, accepted, withheld, provide
     return [subBatchFailedNotice(batch.length, error)];
   }
   for (const item of batch) {
-    const value = result.values.get(item.targetKey);
-    const integrity = result.integrity.get(item.targetKey);
-    if (value !== void 0 && integrity?.matches === true) {
-      accepted.push({
-        targetKey: item.targetKey,
-        entry: { ...syntheticEntry(item), value },
-        lockHash: generatedLockHash(item.governingEntries, item.category)
-      });
-    } else {
-      withheld.push(item.targetKey);
-    }
+    foldGenerationItem(item, result, accepted, withheld, providerFailures);
   }
   return readNotices(result);
 }
+function foldGenerationItem(item, result, accepted, withheld, providerFailures) {
+  const value = result.values.get(item.targetKey);
+  if (value === void 0) {
+    providerFailures.push(item.targetKey);
+    return;
+  }
+  if (result.integrity.get(item.targetKey)?.matches === true) {
+    accepted.push({
+      targetKey: item.targetKey,
+      entry: { ...syntheticEntry(item), value },
+      lockHash: generatedLockHash(item.governingEntries, item.category)
+    });
+  } else {
+    withheld.push(item.targetKey);
+  }
+}
 
 // src/flow/locale-run.ts
 function emptyResource(locale, format) {
@@ -3388,16 +3576,22 @@ async function runSubBatch(provider, params, batch, accepted, integrityMismatche
     return [subBatchFailedNotice(batch.length, error)];
   }
   for (const entry of batch) {
-    const value = result.values.get(entry.key);
-    const integrity = result.integrity.get(entry.key);
-    if (value !== void 0 && integrity?.matches === true) {
-      accepted.set(entry.key, { value, source: entry });
-    } else {
-      integrityMismatches.push(entry.key);
-    }
+    foldEntryResult(entry, result, accepted, integrityMismatches, providerFailures);
   }
   return readNotices(result);
 }
+function foldEntryResult(entry, result, accepted, integrityMismatches, providerFailures) {
+  const value = result.values.get(entry.key);
+  if (value === void 0) {
+    providerFailures.push(entry.key);
+    return;
+  }
+  if (result.integrity.get(entry.key)?.matches === true) {
+    accepted.set(entry.key, { value, source: entry });
+  } else {
+    integrityMismatches.push(entry.key);
+  }
+}
 function computeLockEntries(params, merged, withheld, generated) {
   const lockEntries = {};
   const sourceBaseKeys = sourcePluralBaseKeys(params.source);
@@ -3501,10 +3695,13 @@ var INSTRUCTIONS_LINES = [
   "   structure and the argument names exactly. Translate only the human-readable text.",
   "6. Do not edit the 'Key' column or the hidden 'Source hash' column. They map your translation",
   "   back to the right string. You may sort or filter rows freely; mapping does not depend on row order.",
+  "7. The 'Context' column, when present, is reference text from the source file explaining what the",
+  "   string means or where it is used. It is read-only; leave it as-is.",
   "",
   "Status values:",
   "  new      - this string has no translation yet.",
   "  changed  - the source string changed and the translation needs updating.",
+  "  unchanged - already up to date, included for reference. No action needed.",
   "",
   "When you are done, save the file and send it back. verbatra checks every value on import:",
   "a value with a broken placeholder, invalid ICU, or a source that changed since export is",
@@ -3516,7 +3713,8 @@ var COLUMN = {
   current: 3,
   status: 4,
   translation: 5,
-  sourceHash: 6
+  sourceHash: 6,
+  context: 7
 };
 var HEADERS = [
   "Key",
@@ -3524,7 +3722,8 @@ var HEADERS = [
   "Current translation",
   "Status",
   "Translation",
-  "Source hash"
+  "Source hash",
+  "Context"
 ];
 var HEADER_ROW = 1;
 var INSTRUCTIONS_SHEET_NAME = "Instructions";
@@ -3543,7 +3742,8 @@ var COLUMN_WIDTHS = {
   [COLUMN.source]: 50,
   [COLUMN.current]: 50,
   [COLUMN.status]: 12,
-  [COLUMN.translation]: 50
+  [COLUMN.translation]: 50,
+  [COLUMN.context]: 50
 };
 var TEXT_NUMBER_FORMAT = "@";
 function styleHeader(sheet) {
@@ -3574,7 +3774,8 @@ function writeRow(sheet, sheetRow) {
   translationCell.numFmt = TEXT_NUMBER_FORMAT;
   translationCell.value = sheetRow.translation === "" ? null : sheetRow.translation;
   row.getCell(COLUMN.sourceHash).value = sheetRow.sourceHash;
-  for (let column = COLUMN.key; column <= COLUMN.sourceHash; column += 1) {
+  row.getCell(COLUMN.context).value = sheetRow.context;
+  for (let column = COLUMN.key; column <= COLUMN.context; column += 1) {
     const cell = row.getCell(column);
     cell.protection = { locked: column !== COLUMN.translation };
     if (column !== COLUMN.translation) {
@@ -3599,6 +3800,26 @@ function assertValidWorksheetName(locale) {
     );
   }
 }
+function assertNoWorksheetNameCollisions(sheets) {
+  const reservedKey = INSTRUCTIONS_SHEET_NAME.toLowerCase();
+  const seen = /* @__PURE__ */ new Set();
+  for (const sheet of sheets) {
+    const key = sheet.locale.toLowerCase();
+    if (key === reservedKey) {
+      throw new ExchangeError(
+        "WORKBOOK_INVALID",
+        `The locale "${sheet.locale}" cannot be an Excel worksheet name: it collides with the reserved "${INSTRUCTIONS_SHEET_NAME}" sheet.`
+      );
+    }
+    if (seen.has(key)) {
+      throw new ExchangeError(
+        "WORKBOOK_INVALID",
+        `The locale "${sheet.locale}" cannot be an Excel worksheet name: it collides with another target locale's sheet name.`
+      );
+    }
+    seen.add(key);
+  }
+}
 async function buildDataSheet(workbook, sheet) {
   assertValidWorksheetName(sheet.locale);
   const worksheet = workbook.addWorksheet(sheet.locale);
@@ -3625,6 +3846,7 @@ function buildInstructionsSheet(workbook) {
   sheet.getRow(1).font = { bold: true };
 }
 async function buildWorkbook(model) {
+  assertNoWorksheetNameCollisions(model.sheets);
   const workbook = new ExcelJS__default.default.Workbook();
   buildInstructionsSheet(workbook);
   for (const sheet of model.sheets) {
@@ -3725,9 +3947,10 @@ var rowSchema = zod.z.object({
   key: zod.z.string().min(1),
   source: zod.z.string(),
   currentTarget: zod.z.string(),
-  status: zod.z.enum(["new", "changed"]),
+  status: zod.z.enum(["new", "changed", "unchanged"]),
   sourceHash: zod.z.string(),
-  translation: zod.z.string()
+  translation: zod.z.string(),
+  context: zod.z.string()
 });
 function cellString(cell) {
   const value = cell.value;
@@ -3760,7 +3983,10 @@ function parseRow(sheet, row) {
     currentTarget: cellString(row.getCell(COLUMN.current)),
     status: cellString(row.getCell(COLUMN.status)),
     sourceHash: cellString(row.getCell(COLUMN.sourceHash)),
-    translation: cellString(row.getCell(COLUMN.translation))
+    translation: cellString(row.getCell(COLUMN.translation)),
+    // A workbook built before the Context column existed has no cell here; getCell auto-vivifies an
+    // empty one, so cellString yields "" and the row still validates, keeping import backward-compatible.
+    context: cellString(row.getCell(COLUMN.context))
   };
   const result = rowSchema.safeParse(candidate);
   if (!result.success) {
@@ -3849,14 +4075,15 @@ function buildRows(source, target, baseline, includeUnchanged) {
         currentTarget: target.entries.get(key)?.value ?? "",
         status,
         sourceHash: contentHash(sourceEntry),
-        translation: ""
+        translation: "",
+        context: sourceEntry.description ?? ""
       });
     }
   };
   add(diff2.missing, "new");
   add(diff2.changed, "changed");
   if (includeUnchanged) {
-    add(diff2.unchanged, "changed");
+    add(diff2.unchanged, "unchanged");
   }
   return [...rows].sort((a, b) => a.key < b.key ? -1 : 1);
 }