@verbatra/sdk 0.4.1 → 0.4.3

package/dist/index.d.cts

@@ -37,7 +37,7 @@ type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
  * (counts matter). Always returned (never thrown) for an ordinary mismatch.
  */
 interface PlaceholderIntegrityResult {
-    /** True when nothing is missing or extra and order is preserved. */
+    /** True when nothing is missing or extra: the multisets match, regardless of order. */
     readonly matches: boolean;
     /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
     readonly missing: readonly string[];
@@ -153,8 +153,11 @@ type AnthropicModel = Anthropic.Messages.Model;
  *
  * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
  * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
+ * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
+ *   because DeepL cannot preserve those tokens; such entries are withheld (absent from the result maps)
+ *   rather than sent to DeepL and mangled.
  */
-type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED";
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED" | "PLACEHOLDER_UNSUPPORTED";
 /**
  * An observable, structured signal that something was gracefully degraded (not an
  * error). Carries only a stable code and a static message, never a key or content.
@@ -378,6 +381,8 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   (thrown by `loadConfig`).
  * - `CONFIG_INVALID`: a config was found but is unparseable or fails validation (thrown by `loadConfig`).
  * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format (thrown by `translate`).
+ * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales (thrown by
+ *   `check`, `diff`, and `exportWorkbook` via the shared locale selection).
  * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw; wraps the provider's own error, including
  *   a missing `*_API_KEY` reported as `MISSING_API_KEY` (thrown by `translate`, non-dry-run only).
  * - `SOURCE_UNREADABLE`: the source locale file is absent (thrown by `translate`, and by `watch` at startup).
@@ -388,7 +393,7 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   per-locale failure carries no string code of its own. See the surfaced-not-thrown distinction on
  *   `translate`.
  */
-type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCALE_FAILED";
+type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCALE_FAILED";
 /** The single structured error the SDK throws or records. Never carries a secret. */
 declare class SdkError extends Error {
     /** The stable {@link SdkErrorCode} for this failure; branch on this, not the message. */
@@ -648,7 +653,8 @@ interface CheckDeps {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns The aggregate and per-locale drift status.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function check(input: CheckInput, deps?: CheckDeps): Promise<CheckSummary>;
 
@@ -697,7 +703,8 @@ interface DiffDeps {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns The aggregate and per-locale pending change.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
@@ -897,7 +904,8 @@ interface ExportWorkbookResult {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns Where the workbook was written and the per-locale row counts.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;
 

package/dist/index.d.ts

@@ -37,7 +37,7 @@ type TranslationEntry$1 = Readonly<z.infer<typeof translationEntrySchema$1>>;
  * (counts matter). Always returned (never thrown) for an ordinary mismatch.
  */
 interface PlaceholderIntegrityResult {
-    /** True when nothing is missing or extra and order is preserved. */
+    /** True when nothing is missing or extra: the multisets match, regardless of order. */
     readonly matches: boolean;
     /** Occurrences present in source but absent from the translation, one per dropped occurrence. Sorted. */
     readonly missing: readonly string[];
@@ -153,8 +153,11 @@ type AnthropicModel = Anthropic.Messages.Model;
  *
  * - `FORMALITY_DOWNGRADED`: a requested formality was not applied (the free tier does not support it).
  * - `GLOSSARY_IGNORED`: a supplied generic glossary was not applied.
+ * - `PLACEHOLDER_UNSUPPORTED`: at least one placeholder- or ICU-bearing entry was left untranslated
+ *   because DeepL cannot preserve those tokens; such entries are withheld (absent from the result maps)
+ *   rather than sent to DeepL and mangled.
  */
-type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED";
+type ProviderNoticeCode = "FORMALITY_DOWNGRADED" | "GLOSSARY_IGNORED" | "PLACEHOLDER_UNSUPPORTED";
 /**
  * An observable, structured signal that something was gracefully degraded (not an
  * error). Carries only a stable code and a static message, never a key or content.
@@ -378,6 +381,8 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   (thrown by `loadConfig`).
  * - `CONFIG_INVALID`: a config was found but is unparseable or fails validation (thrown by `loadConfig`).
  * - `UNKNOWN_FORMAT`: no adapter is registered for the configured format (thrown by `translate`).
+ * - `UNKNOWN_LOCALE`: a requested locale is not among the configured target locales (thrown by
+ *   `check`, `diff`, and `exportWorkbook` via the shared locale selection).
  * - `PROVIDER_CONSTRUCTION_FAILED`: the provider factory threw; wraps the provider's own error, including
  *   a missing `*_API_KEY` reported as `MISSING_API_KEY` (thrown by `translate`, non-dry-run only).
  * - `SOURCE_UNREADABLE`: the source locale file is absent (thrown by `translate`, and by `watch` at startup).
@@ -388,7 +393,7 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<VerbatraConfig
  *   per-locale failure carries no string code of its own. See the surfaced-not-thrown distinction on
  *   `translate`.
  */
-type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCALE_FAILED";
+type SdkErrorCode = "CONFIG_NOT_FOUND" | "CONFIG_INVALID" | "UNKNOWN_FORMAT" | "UNKNOWN_LOCALE" | "PROVIDER_CONSTRUCTION_FAILED" | "SOURCE_UNREADABLE" | "SOURCE_INVALID" | "LOCK_FILE_INVALID" | "LOCALE_FAILED";
 /** The single structured error the SDK throws or records. Never carries a secret. */
 declare class SdkError extends Error {
     /** The stable {@link SdkErrorCode} for this failure; branch on this, not the message. */
@@ -648,7 +653,8 @@ interface CheckDeps {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns The aggregate and per-locale drift status.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function check(input: CheckInput, deps?: CheckDeps): Promise<CheckSummary>;
 
@@ -697,7 +703,8 @@ interface DiffDeps {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns The aggregate and per-locale pending change.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function diff(input: DiffInput, deps?: DiffDeps): Promise<DiffSummary>;
 
@@ -897,7 +904,8 @@ interface ExportWorkbookResult {
  * @param deps - Optional composition seams (registry, file system) for tests.
  * @returns Where the workbook was written and the per-locale row counts.
  * @throws {@link SdkError} `UNKNOWN_FORMAT`, `SOURCE_UNREADABLE`, `SOURCE_INVALID`, `LOCK_FILE_INVALID`
- *   with the same meanings as in `translate`.
+ *   with the same meanings as in `translate`, or `UNKNOWN_LOCALE` when a requested locale is not
+ *   among the configured target locales.
  */
 declare function exportWorkbook(input: ExportWorkbookInput, deps?: ExportWorkbookDeps): Promise<ExportWorkbookResult>;
 

package/dist/index.js

@@ -15,6 +15,7 @@ import { parse as parse$1, TYPE } from '@formatjs/icu-messageformat-parser';
 import { XMLSerializer, DOMParser } from '@xmldom/xmldom';
 import { stringify, parse } from 'yaml';
 import ExcelJS from 'exceljs';
+import { Readable } from 'stream';
 import JSZip from 'jszip';
 import { watch as watch$1 } from 'chokidar';
 
@@ -151,7 +152,7 @@ function checkPlaceholders(source, translated) {
   const extra = multisetExcess(translatedCounts, sourceCounts);
   const reordered = missing.length === 0 && extra.length === 0 && !sameOrder(source, translated);
   return {
-    matches: missing.length === 0 && extra.length === 0 && !reordered,
+    matches: missing.length === 0 && extra.length === 0,
     missing,
     extra,
     reordered
@@ -472,6 +473,19 @@ function createDefaultClient2() {
   };
   return { client, freeAccount };
 }
+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 = [];
+  const unprotectable = [];
+  for (const entry of entries) {
+    if (entry.placeholders.length > 0) {
+      unprotectable.push(entry);
+    } else {
+      protectable.push(entry);
+    }
+  }
+  return { protectable, unprotectable };
+}
 var FORMALITY_DOWNGRADED_MESSAGE = "Formality was not applied: the configured DeepL key is a free-tier key, which does not support formality.";
 var GLOSSARY_IGNORED_MESSAGE = "The supplied glossary term map was not applied: DeepL uses configured glossary IDs, not term maps.";
 function buildTranslateOptions(input) {
@@ -535,6 +549,7 @@ function resolveClient(deps) {
 }
 async function translate(bundle, config, request) {
   const data = validateRequest(request);
+  const { protectable, unprotectable } = partitionByPlaceholders(data.entries);
   const genericGlossarySupplied = request.glossary !== void 0 && Object.keys(request.glossary).length > 0;
   const { options, notices } = buildTranslateOptions({
     freeAccount: bundle.freeAccount,
@@ -542,18 +557,28 @@ async function translate(bundle, config, request) {
     ...data.tone !== void 0 ? { tone: data.tone } : {},
     ...config.glossaryId !== void 0 ? { glossaryId: config.glossaryId } : {}
   });
-  const texts = data.entries.map((entry) => entry.value);
-  const results = await callClient2(
+  const { values, integrity } = await translateProtectable(
     bundle.client,
-    texts,
-    data.sourceLocale,
-    data.targetLocale,
-    options
+    data,
+    protectable,
+    options,
+    request.extractPlaceholders
   );
-  const { values, integrityInputs } = zipResults(data.entries, results);
-  const integrity = checkBatchIntegrity(integrityInputs, request.extractPlaceholders);
+  if (unprotectable.length > 0) {
+    notices.push({ code: "PLACEHOLDER_UNSUPPORTED", message: PLACEHOLDER_UNSUPPORTED_MESSAGE });
+  }
   return { values, integrity, notices };
 }
+async function translateProtectable(client, data, protectable, options, extract) {
+  if (protectable.length === 0) {
+    return { values: /* @__PURE__ */ new Map(), integrity: /* @__PURE__ */ new Map() };
+  }
+  const texts = protectable.map((entry) => entry.value);
+  const results = await callClient2(client, texts, data.sourceLocale, data.targetLocale, options);
+  const { values, integrityInputs } = zipResults(protectable, results);
+  const integrity = checkBatchIntegrity(integrityInputs, extract);
+  return { values, integrity };
+}
 function callClient2(client, texts, sourceLang, targetLang, options) {
   return guardProviderCall(() => client.translateText(texts, sourceLang, targetLang, options));
 }
@@ -2057,6 +2082,24 @@ function selectAdapter(format, registry = createDefaultRegistry()) {
   );
 }
 
+// src/flow/select-locales.ts
+function selectLocales(config, requested) {
+  if (requested === void 0) {
+    return config.targetLocales;
+  }
+  const configured = new Set(config.targetLocales);
+  const unknown = requested.filter((locale) => !configured.has(locale));
+  if (unknown.length > 0) {
+    const label = unknown.length === 1 ? "locale" : "locales";
+    throw new SdkError(
+      "UNKNOWN_LOCALE",
+      `Requested ${label} not in the configured target locales: ${unknown.join(", ")}. Configured targets: ${config.targetLocales.join(", ")}.`
+    );
+  }
+  const wanted = new Set(requested);
+  return config.targetLocales.filter((locale) => wanted.has(locale));
+}
+
 // src/flow/source.ts
 async function readSource(config, cwd, fs, adapter) {
   const sourcePath = localeFilePath(cwd, config.files.pattern, config.sourceLocale);
@@ -2085,13 +2128,6 @@ async function readTarget(cwd, config, adapter, fs, locale) {
   }
   return (await adapter.read(path, locale)).resource;
 }
-function selectedLocales(config, requested) {
-  if (requested === void 0) {
-    return config.targetLocales;
-  }
-  const wanted = new Set(requested);
-  return config.targetLocales.filter((locale) => wanted.has(locale));
-}
 async function diffLocales(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
@@ -2100,7 +2136,7 @@ async function diffLocales(input, deps = {}) {
   const source = await readSource(config, cwd, fs, adapter);
   const lock = await readLockFile(lockFilePath(cwd), fs);
   return Promise.all(
-    selectedLocales(config, input.locales).map(async (locale) => {
+    selectLocales(config, input.locales).map(async (locale) => {
       const target = await readTarget(cwd, config, adapter, fs, locale);
       const diff2 = diffResources(source.resource, target, { baseline: baselineFor(lock, locale) });
       return { locale, diff: diff2 };
@@ -2826,6 +2862,34 @@ function declaredSize(file) {
   const size = data?.uncompressedSize;
   return typeof size === "number" && Number.isFinite(size) ? size : void 0;
 }
+async function streamEntryBounded(file, remaining) {
+  const chunks = [];
+  let raw = 0;
+  let oversize = false;
+  const source = new Readable({ objectMode: true }).wrap(
+    file.nodeStream("nodebuffer")
+  );
+  try {
+    for await (const chunk2 of source) {
+      const buf = Buffer.isBuffer(chunk2) ? chunk2 : Buffer.from(chunk2);
+      raw += buf.length;
+      if (raw > remaining) {
+        oversize = true;
+        break;
+      }
+      chunks.push(buf);
+    }
+  } catch {
+    throw new ExchangeError("WORKBOOK_INVALID", "A workbook entry could not be decompressed.");
+  }
+  if (oversize) {
+    throw new ExchangeError(
+      "WORKBOOK_INVALID",
+      "The workbook decompresses to more than the permitted maximum bytes."
+    );
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
 async function guardWorkbookBytes(bytes, limits) {
   let zip;
   try {
@@ -2855,12 +2919,8 @@ async function guardWorkbookBytes(bytes, limits) {
   }
   let actualTotal = 0;
   for (const file of files) {
-    let content;
-    try {
-      content = await file.async("string");
-    } catch {
-      throw new ExchangeError("WORKBOOK_INVALID", "A workbook entry could not be decompressed.");
-    }
+    const remaining = limits.maxDecompressedBytes - actualTotal;
+    const content = await streamEntryBounded(file, remaining);
     actualTotal += Buffer.byteLength(content, "utf8");
     if (actualTotal > limits.maxDecompressedBytes) {
       throw new ExchangeError(
@@ -3010,13 +3070,6 @@ function buildRows(source, target, baseline, includeUnchanged) {
   }
   return [...rows].sort((a, b) => a.key < b.key ? -1 : 1);
 }
-function selectedLocales2(config, requested) {
-  if (requested === void 0) {
-    return config.targetLocales;
-  }
-  const wanted = new Set(requested);
-  return config.targetLocales.filter((locale) => wanted.has(locale));
-}
 async function exportWorkbook(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
@@ -3024,7 +3077,7 @@ async function exportWorkbook(input, deps = {}) {
   const adapter = selectAdapter(config.format, deps.adapterRegistry);
   const source = await readSource(config, cwd, fs, adapter);
   const lock = await readLockFile(lockFilePath(cwd), fs);
-  const locales = selectedLocales2(config, input.locales);
+  const locales = selectLocales(config, input.locales);
   const sheets = await Promise.all(
     locales.map(async (locale) => {
       const target = await readTarget3(cwd, config, adapter, fs, locale);