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

package/dist/index.cjs

@@ -807,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 = [];
@@ -886,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({
@@ -913,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,
@@ -931,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()
@@ -1402,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),
@@ -1443,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"]
@@ -2158,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.");
   }
@@ -2181,6 +2267,7 @@ function createTreeFileAdapter(options) {
     validateTree,
     buildWriteTree,
     comparePlaceholders,
+    deriveDescriptions,
     keyMode = "literal-leaf"
   } = options;
   return {
@@ -2192,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 };
@@ -2233,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) {
@@ -2289,7 +2409,8 @@ function createArbAdapter() {
     computeInvalidIcuKeys: icuInvalidKeys,
     validateMessage: icuIsValid,
     comparePlaceholders: compareIcuPlaceholders,
-    buildWriteTree: buildArbWriteTree
+    buildWriteTree: buildArbWriteTree,
+    deriveDescriptions: extractArbDescriptions
   });
 }
 function createJsonFileAdapter(options) {
@@ -2595,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 } : {}
       });
     }
   });
@@ -2614,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 } : {}
+        });
       }
     });
   });
@@ -2658,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;
@@ -3549,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",
@@ -3564,7 +3713,8 @@ var COLUMN = {
   current: 3,
   status: 4,
   translation: 5,
-  sourceHash: 6
+  sourceHash: 6,
+  context: 7
 };
 var HEADERS = [
   "Key",
@@ -3572,7 +3722,8 @@ var HEADERS = [
   "Current translation",
   "Status",
   "Translation",
-  "Source hash"
+  "Source hash",
+  "Context"
 ];
 var HEADER_ROW = 1;
 var INSTRUCTIONS_SHEET_NAME = "Instructions";
@@ -3591,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) {
@@ -3622,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) {
@@ -3647,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);
@@ -3673,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) {
@@ -3773,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;
@@ -3808,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) {
@@ -3897,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);
 }