@verbatra/sdk 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -12,6 +12,8 @@ var genai = require('@google/genai');
 var OpenAI = require('openai');
 var promises = require('fs/promises');
 var icuMessageformatParser = require('@formatjs/icu-messageformat-parser');
+var ExcelJS = require('exceljs');
+var JSZip = require('jszip');
 var chokidar = require('chokidar');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -38,6 +40,8 @@ var Anthropic__default = /*#__PURE__*/_interopDefault(Anthropic);
 var deepl__namespace = /*#__PURE__*/_interopNamespace(deepl);
 var log__default = /*#__PURE__*/_interopDefault(log);
 var OpenAI__default = /*#__PURE__*/_interopDefault(OpenAI);
+var ExcelJS__default = /*#__PURE__*/_interopDefault(ExcelJS);
+var JSZip__default = /*#__PURE__*/_interopDefault(JSZip);
 
 // src/config/define-config.ts
 function defineConfig(config) {
@@ -907,9 +911,41 @@ async function readBounded(path, maxBytes) {
     await handle.close();
   }
 }
+async function readBoundedBytesInto(handle, size) {
+  const buffer = Buffer.allocUnsafeSlow(size);
+  let offset = 0;
+  while (offset < size) {
+    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+    if (bytesRead === 0) {
+      break;
+    }
+    offset += bytesRead;
+  }
+  return new Uint8Array(buffer.buffer, buffer.byteOffset, offset);
+}
+async function readBoundedBytes(path, maxBytes) {
+  let handle;
+  try {
+    handle = await promises.open(path, "r");
+  } catch {
+    return { kind: "missing" };
+  }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      return { kind: "missing" };
+    }
+    if (info.size > maxBytes) {
+      return { kind: "too-large" };
+    }
+    return { kind: "ok", bytes: await readBoundedBytesInto(handle, info.size) };
+  } finally {
+    await handle.close();
+  }
+}
 async function atomicWrite(path$1, data) {
   const tmp = path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}`);
-  await promises.writeFile(tmp, data, "utf8");
+  await (typeof data === "string" ? promises.writeFile(tmp, data, "utf8") : promises.writeFile(tmp, data));
   try {
     await promises.rename(tmp, path$1);
   } catch (error) {
@@ -927,7 +963,9 @@ var defaultFs = {
     }
   },
   readFileBounded: (path, maxBytes) => readBounded(path, maxBytes),
-  writeFile: (path, data) => atomicWrite(path, data)
+  readBytesBounded: (path, maxBytes) => readBoundedBytes(path, maxBytes),
+  writeFile: (path, data) => atomicWrite(path, data),
+  writeBytes: (path, data) => atomicWrite(path, data)
 };
 var LOCK_FILE_NAME = "verbatra.lock.json";
 var CURRENT_VERSION = 1;
@@ -1174,6 +1212,7 @@ function createJsonFileAdapter(options) {
     deriveEntry,
     extractPlaceholders: extractPlaceholders2,
     computeInvalidIcuKeys: computeInvalidIcuKeys2,
+    validateMessage: validateMessage2,
     validateTree,
     buildWriteTree
   } = options;
@@ -1181,6 +1220,8 @@ function createJsonFileAdapter(options) {
     format,
     canHandle,
     extractPlaceholders: extractPlaceholders2,
+    // Non-ICU formats supply no validator: every value is valid for their syntax.
+    validateMessage: validateMessage2 ?? (() => true),
     async read(filePath, locale) {
       const outcome = await readBounded2(filePath);
       if (outcome.kind === "not-a-file") {
@@ -1296,10 +1337,13 @@ function analyzeIcuValue(value) {
 function extractPlaceholders(value) {
   return analyzeIcuValue(value).placeholders;
 }
+function validateMessage(value) {
+  return analyzeIcuValue(value).valid;
+}
 function computeInvalidIcuKeys(entries) {
   const invalid = [];
   for (const [key, entry] of entries) {
-    if (!analyzeIcuValue(entry.value).valid) {
+    if (!validateMessage(entry.value)) {
       invalid.push(key);
     }
   }
@@ -1313,7 +1357,8 @@ function createNextIntlJsonAdapter() {
       const analysis = analyzeIcuValue(value);
       return { placeholders: analysis.placeholders, isPlural: analysis.isPlural };
     },
-    computeInvalidIcuKeys
+    computeInvalidIcuKeys,
+    validateMessage
   });
 }
 function assertNotMixed(tree) {
@@ -1480,6 +1525,33 @@ function selectProvider(config, createProvider = buildProvider) {
   }
 }
 
+// src/flow/locale-failure.ts
+function describeError(error) {
+  if (error instanceof Error) {
+    const code = error.code;
+    return { code: typeof code === "string" ? code : "LOCALE_FAILED", message: error.message };
+  }
+  return { code: "LOCALE_FAILED", message: String(error) };
+}
+function failureSummary(locale, error) {
+  return {
+    locale,
+    status: "failed",
+    translated: [],
+    unchanged: [],
+    orphaned: [],
+    invalidIcuSource: [],
+    integrityMismatches: [],
+    notices: [],
+    error: describeError(error)
+  };
+}
+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 };
+}
+
 // src/flow/notices.ts
 function isNotice(value) {
   return typeof value === "object" && value !== null && typeof value.code === "string" && typeof value.message === "string";
@@ -1605,27 +1677,7 @@ function computeLockEntries(params, merged, withheld) {
   return lockEntries;
 }
 
-// src/flow/translate-project.ts
-function describeError(error) {
-  if (error instanceof Error) {
-    const code = error.code;
-    return { code: typeof code === "string" ? code : "LOCALE_FAILED", message: error.message };
-  }
-  return { code: "LOCALE_FAILED", message: String(error) };
-}
-function failureSummary(locale, error) {
-  return {
-    locale,
-    status: "failed",
-    translated: [],
-    unchanged: [],
-    orphaned: [],
-    invalidIcuSource: [],
-    integrityMismatches: [],
-    notices: [],
-    error: describeError(error)
-  };
-}
+// src/flow/source.ts
 async function readSource(config, cwd, fs, adapter) {
   const sourcePath = localeFilePath(cwd, config.files.pattern, config.sourceLocale);
   if (!await fs.fileExists(sourcePath)) {
@@ -1644,6 +1696,8 @@ async function readSource(config, cwd, fs, adapter) {
     );
   }
 }
+
+// src/flow/translate-project.ts
 async function translate2(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
@@ -1682,12 +1736,594 @@ async function translate2(input, deps = {}) {
       summaries.push(failureSummary(targetLocale, error));
     }
   }
-  return aggregate(dryRun, summaries);
+  const { succeeded, failed } = partition(summaries);
+  return { dryRun, locales: summaries, succeeded, failed };
 }
-function aggregate(dryRun, 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 { dryRun, locales, succeeded, failed };
+var ExchangeError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ExchangeError";
+    this.code = code;
+  }
+};
+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.",
+  "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.",
+  "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",
+  "   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.",
+  "",
+  "Status values:",
+  "  new      - this string has no translation yet.",
+  "  changed  - the source string changed and the translation needs updating.",
+  "",
+  "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",
+  "withheld (not written) and reported so you can fix and resubmit it."
+];
+var COLUMN = {
+  key: 1,
+  source: 2,
+  current: 3,
+  status: 4,
+  translation: 5,
+  sourceHash: 6
+};
+var HEADERS = [
+  "Key",
+  "Source",
+  "Current translation",
+  "Status",
+  "Translation",
+  "Source hash"
+];
+var HEADER_ROW = 1;
+var INSTRUCTIONS_SHEET_NAME = "Instructions";
+var READ_ONLY_FILL = {
+  type: "pattern",
+  pattern: "solid",
+  fgColor: { argb: "FFF1F3F5" }
+};
+var HEADER_FILL = {
+  type: "pattern",
+  pattern: "solid",
+  fgColor: { argb: "FFDDE3EA" }
+};
+var COLUMN_WIDTHS = {
+  [COLUMN.key]: 36,
+  [COLUMN.source]: 50,
+  [COLUMN.current]: 50,
+  [COLUMN.status]: 12,
+  [COLUMN.translation]: 50
+};
+function styleHeader(sheet) {
+  const header = sheet.getRow(HEADER_ROW);
+  HEADERS.forEach((label, index) => {
+    const cell = header.getCell(index + 1);
+    cell.value = label;
+    cell.font = { bold: true };
+    cell.fill = HEADER_FILL;
+  });
+  header.commit();
+}
+function applyColumnGeometry(sheet) {
+  for (const [column, width] of Object.entries(COLUMN_WIDTHS)) {
+    sheet.getColumn(Number(column)).width = width;
+  }
+  sheet.getColumn(COLUMN.sourceHash).hidden = true;
+  sheet.views = [{ state: "frozen", ySplit: HEADER_ROW }];
+}
+function writeRow(sheet, sheetRow) {
+  const row = sheet.addRow([]);
+  row.getCell(COLUMN.key).value = sheetRow.key;
+  row.getCell(COLUMN.source).value = sheetRow.source;
+  row.getCell(COLUMN.current).value = sheetRow.currentTarget;
+  row.getCell(COLUMN.status).value = sheetRow.status;
+  row.getCell(COLUMN.translation).value = sheetRow.translation === "" ? null : sheetRow.translation;
+  row.getCell(COLUMN.sourceHash).value = sheetRow.sourceHash;
+  for (let column = COLUMN.key; column <= COLUMN.sourceHash; column += 1) {
+    const cell = row.getCell(column);
+    cell.protection = { locked: column !== COLUMN.translation };
+    if (column !== COLUMN.translation) {
+      cell.fill = READ_ONLY_FILL;
+    }
+  }
+  row.commit();
+}
+var MAX_WORKSHEET_NAME_LENGTH = 31;
+var FORBIDDEN_WORKSHEET_NAME_CHARS = /[:\\/?*[\]]/;
+function assertValidWorksheetName(locale) {
+  if (locale.length === 0 || locale.length > MAX_WORKSHEET_NAME_LENGTH) {
+    throw new ExchangeError(
+      "WORKBOOK_INVALID",
+      `The locale "${locale}" cannot be an Excel worksheet name: it must be 1 to ${MAX_WORKSHEET_NAME_LENGTH} characters.`
+    );
+  }
+  if (FORBIDDEN_WORKSHEET_NAME_CHARS.test(locale)) {
+    throw new ExchangeError(
+      "WORKBOOK_INVALID",
+      `The locale "${locale}" cannot be an Excel worksheet name: it must not contain any of : \\ / ? * [ ].`
+    );
+  }
+}
+async function buildDataSheet(workbook, sheet) {
+  assertValidWorksheetName(sheet.locale);
+  const worksheet = workbook.addWorksheet(sheet.locale);
+  styleHeader(worksheet);
+  for (const row of sheet.rows) {
+    writeRow(worksheet, row);
+  }
+  applyColumnGeometry(worksheet);
+  await worksheet.protect("", {
+    spinCount: 0,
+    selectLockedCells: true,
+    selectUnlockedCells: true,
+    formatColumns: true,
+    sort: true,
+    autoFilter: true
+  });
+}
+function buildInstructionsSheet(workbook) {
+  const sheet = workbook.addWorksheet(INSTRUCTIONS_SHEET_NAME);
+  sheet.getColumn(1).width = 110;
+  for (const line of INSTRUCTIONS_LINES) {
+    sheet.addRow([line]);
+  }
+  sheet.getRow(1).font = { bold: true };
+}
+async function buildWorkbook(model) {
+  const workbook = new ExcelJS__default.default.Workbook();
+  buildInstructionsSheet(workbook);
+  for (const sheet of model.sheets) {
+    await buildDataSheet(workbook, sheet);
+  }
+  try {
+    const buffer = await workbook.xlsx.writeBuffer();
+    const view = buffer;
+    return Uint8Array.prototype.slice.call(view);
+  } catch {
+    throw new ExchangeError("WORKBOOK_INVALID", "The workbook could not be serialized.");
+  }
+}
+var DEFAULT_WORKBOOK_LIMITS = {
+  maxDecompressedBytes: 64 * 1024 * 1024,
+  maxEntryCount: 1024,
+  maxSheetCount: 256,
+  maxRowsPerSheet: 1e5,
+  maxCellsPerRow: 64
+};
+function assertNoDoctype(name, xml) {
+  if (/<!DOCTYPE/i.test(xml) || /<!ENTITY/i.test(xml)) {
+    throw new ExchangeError(
+      "WORKBOOK_INVALID",
+      `A workbook XML part (${name}) declares a DTD or entity, which is not permitted.`
+    );
+  }
+}
+function declaredSize(file) {
+  const data = file._data;
+  const size = data?.uncompressedSize;
+  return typeof size === "number" && Number.isFinite(size) ? size : void 0;
+}
+async function guardWorkbookBytes(bytes, limits) {
+  let zip;
+  try {
+    zip = await JSZip__default.default.loadAsync(bytes);
+  } catch {
+    throw new ExchangeError("WORKBOOK_INVALID", "The workbook is not a readable xlsx container.");
+  }
+  const files = Object.values(zip.files).filter((file) => !file.dir);
+  if (files.length > limits.maxEntryCount) {
+    throw new ExchangeError(
+      "WORKBOOK_INVALID",
+      `The workbook has more than the maximum of ${limits.maxEntryCount} entries.`
+    );
+  }
+  let declaredTotal = 0;
+  for (const file of files) {
+    const size = declaredSize(file);
+    if (size !== void 0) {
+      declaredTotal += size;
+      if (declaredTotal > limits.maxDecompressedBytes) {
+        throw new ExchangeError(
+          "WORKBOOK_INVALID",
+          `The workbook decompresses to more than the maximum of ${limits.maxDecompressedBytes} bytes.`
+        );
+      }
+    }
+  }
+  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.");
+    }
+    actualTotal += Buffer.byteLength(content, "utf8");
+    if (actualTotal > limits.maxDecompressedBytes) {
+      throw new ExchangeError(
+        "WORKBOOK_INVALID",
+        `The workbook decompresses to more than the maximum of ${limits.maxDecompressedBytes} bytes.`
+      );
+    }
+    assertNoDoctype(file.name, content);
+  }
+}
+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"]),
+  sourceHash: zod.z.string(),
+  translation: zod.z.string()
+});
+function cellString(cell) {
+  const value = cell.value;
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return typeof cell.text === "string" ? cell.text : "";
+}
+function assertHeader(sheet) {
+  const header = sheet.getRow(HEADER_ROW);
+  const key = cellString(header.getCell(COLUMN.key));
+  const sourceHash = cellString(header.getCell(COLUMN.sourceHash));
+  if (key !== HEADERS[COLUMN.key - 1] || sourceHash !== HEADERS[COLUMN.sourceHash - 1]) {
+    throw new ExchangeError(
+      "WORKBOOK_INVALID",
+      `The sheet "${sheet.name}" is missing the expected Key and Source hash columns.`
+    );
+  }
+}
+function parseRow(sheet, 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))
+  };
+  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 result.data;
+}
+function readDataSheet(sheet, limits) {
+  assertHeader(sheet);
+  if (sheet.rowCount - HEADER_ROW > limits.maxRowsPerSheet) {
+    throw new ExchangeError(
+      "WORKBOOK_INVALID",
+      `The sheet "${sheet.name}" has more than the maximum of ${limits.maxRowsPerSheet} rows.`
+    );
+  }
+  const rows = [];
+  for (let rowNumber = HEADER_ROW + 1; rowNumber <= sheet.rowCount; rowNumber += 1) {
+    const row = sheet.getRow(rowNumber);
+    if (row.cellCount > limits.maxCellsPerRow) {
+      throw new ExchangeError(
+        "WORKBOOK_INVALID",
+        `The sheet "${sheet.name}" has a row with more than the maximum of ${limits.maxCellsPerRow} cells.`
+      );
+    }
+    if (cellString(row.getCell(COLUMN.key)) === "") {
+      continue;
+    }
+    rows.push(parseRow(sheet, row));
+  }
+  return { locale: sheet.name, rows };
+}
+async function loadWorkbook(bytes) {
+  const workbook = new ExcelJS__default.default.Workbook();
+  try {
+    const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    await workbook.xlsx.load(buffer);
+  } catch {
+    throw new ExchangeError("WORKBOOK_INVALID", "The workbook could not be parsed as xlsx.");
+  }
+  return workbook;
+}
+async function readWorkbook(bytes, options = {}) {
+  const limits = options.limits ?? DEFAULT_WORKBOOK_LIMITS;
+  await guardWorkbookBytes(bytes, limits);
+  const workbook = await loadWorkbook(bytes);
+  if (workbook.worksheets.length > limits.maxSheetCount) {
+    throw new ExchangeError(
+      "WORKBOOK_INVALID",
+      `The workbook has more than the maximum of ${limits.maxSheetCount} sheets.`
+    );
+  }
+  const sheets = [];
+  for (const sheet of workbook.worksheets) {
+    if (sheet.name === INSTRUCTIONS_SHEET_NAME) {
+      continue;
+    }
+    sheets.push(readDataSheet(sheet, limits));
+  }
+  return { sheets };
+}
+
+// src/flow/workbook/export-workbook.ts
+var DEFAULT_WORKBOOK_PATH = "verbatra-translations.xlsx";
+async function readTarget2(cwd, config, adapter, fs, locale) {
+  const path = localeFilePath(cwd, config.files.pattern, locale);
+  if (!await fs.fileExists(path)) {
+    return { locale, namespace: "", format: config.format, entries: /* @__PURE__ */ new Map() };
+  }
+  return (await adapter.read(path, locale)).resource;
+}
+function buildRows(source, target, baseline, includeUnchanged) {
+  const diff = diffResources(source, target, { baseline });
+  const rows = [];
+  const add = (keys, status) => {
+    for (const key of keys) {
+      const sourceEntry = source.entries.get(key);
+      if (sourceEntry === void 0) {
+        continue;
+      }
+      rows.push({
+        key,
+        source: sourceEntry.value,
+        currentTarget: target.entries.get(key)?.value ?? "",
+        status,
+        sourceHash: contentHash(sourceEntry),
+        translation: ""
+      });
+    }
+  };
+  add(diff.missing, "new");
+  add(diff.changed, "changed");
+  if (includeUnchanged) {
+    add(diff.unchanged, "changed");
+  }
+  return [...rows].sort((a, b) => a.key < b.key ? -1 : 1);
+}
+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 exportWorkbook(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const fs = deps.fs ?? defaultFs;
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const source = await readSource(config, cwd, fs, adapter);
+  const lock = await readLockFile(lockFilePath(cwd), fs);
+  const locales = selectedLocales(config, input.locales);
+  const sheets = await Promise.all(
+    locales.map(async (locale) => {
+      const target = await readTarget2(cwd, config, adapter, fs, locale);
+      const rows = buildRows(
+        source.resource,
+        target,
+        baselineFor(lock, locale),
+        input.includeUnchanged ?? false
+      );
+      return { locale, rows };
+    })
+  );
+  const model = { sheets };
+  const bytes = await buildWorkbook(model);
+  const path$1 = path.resolve(cwd, input.out ?? DEFAULT_WORKBOOK_PATH);
+  await fs.writeBytes(path$1, bytes);
+  return {
+    path: path$1,
+    locales: sheets.map((sheet) => ({ locale: sheet.locale, rows: sheet.rows.length }))
+  };
+}
+
+// src/flow/workbook/import-locale.ts
+var UnknownKeyError = class extends Error {
+  key;
+  constructor(key) {
+    super(`The workbook has a row with key "${key}" that maps to no known source or target key.`);
+    this.name = "UnknownKeyError";
+    this.key = key;
+  }
+};
+function isUnknownKey(row, source, target) {
+  return !source.entries.has(row.key) && !target.entries.has(row.key);
+}
+function judge(row, sourceEntry, adapter) {
+  if (contentHash(sourceEntry) !== row.sourceHash) {
+    return "drift";
+  }
+  const integrity = checkPlaceholders(
+    sourceEntry.placeholders,
+    adapter.extractPlaceholders(row.translation)
+  );
+  if (!integrity.matches) {
+    return "placeholder";
+  }
+  if (!adapter.validateMessage(row.translation)) {
+    return "icu";
+  }
+  return void 0;
+}
+function classifyRows(params, buckets) {
+  for (const row of params.sheet.rows) {
+    if (row.translation === "") {
+      continue;
+    }
+    if (isUnknownKey(row, params.source, params.target)) {
+      throw new UnknownKeyError(row.key);
+    }
+    const sourceEntry = params.source.entries.get(row.key);
+    if (sourceEntry === void 0) {
+      continue;
+    }
+    const reason = judge(row, sourceEntry, params.adapter);
+    if (reason === void 0) {
+      buckets.accepted.set(row.key, { value: row.translation, source: sourceEntry });
+    } else {
+      buckets.mismatches.push(row.key);
+      buckets.withheld.add(row.key);
+    }
+  }
+}
+function importLocale(params) {
+  const diff = diffResources(params.source, params.target, { baseline: params.baseline });
+  const buckets = { accepted: /* @__PURE__ */ new Map(), mismatches: [], withheld: /* @__PURE__ */ new Set() };
+  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 summary = {
+    locale: params.sheet.locale,
+    status: "succeeded",
+    translated: [...buckets.accepted.keys()].sort(),
+    unchanged: diff.unchanged,
+    orphaned: diff.orphaned,
+    invalidIcuSource,
+    integrityMismatches: [...buckets.mismatches].sort(),
+    notices: []
+  };
+  return { summary, accepted: buckets.accepted, withheld: buckets.withheld };
+}
+
+// src/flow/workbook/import-workbook.ts
+var MAX_WORKBOOK_FILE_BYTES = 64 * 1024 * 1024;
+async function readWorkbookBytes(path, fs) {
+  const read = await fs.readBytesBounded(path, MAX_WORKBOOK_FILE_BYTES);
+  if (read.kind === "missing") {
+    throw new SdkError("SOURCE_UNREADABLE", `The workbook was not found at ${path}.`);
+  }
+  if (read.kind === "too-large") {
+    throw new SdkError(
+      "SOURCE_INVALID",
+      `The workbook at ${path} exceeds the maximum allowed size of ${MAX_WORKBOOK_FILE_BYTES} bytes.`
+    );
+  }
+  return read.bytes;
+}
+async function readTarget3(cwd, config, adapter, fs, locale) {
+  const path = localeFilePath(cwd, config.files.pattern, locale);
+  if (!await fs.fileExists(path)) {
+    return { locale, namespace: "", format: config.format, entries: /* @__PURE__ */ new Map() };
+  }
+  return (await adapter.read(path, locale)).resource;
+}
+function mergeAccepted(target, accepted) {
+  const merged = new Map(target.entries);
+  for (const [key, { value, source }] of accepted) {
+    merged.set(key, { ...source, value, namespace: target.namespace });
+  }
+  return merged;
+}
+function computeLockEntries2(source, merged, baseline, withheld) {
+  const entries = {};
+  for (const key of merged.keys()) {
+    const sourceEntry = source.entries.get(key);
+    if (sourceEntry === void 0) {
+      continue;
+    }
+    if (withheld.has(key)) {
+      const prior = baseline.get(key);
+      if (prior !== void 0) {
+        entries[key] = prior;
+      }
+      continue;
+    }
+    entries[key] = contentHash(sourceEntry);
+  }
+  return entries;
+}
+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.`
+    );
+  }
+  const target = await readTarget3(ctx.cwd, ctx.config, ctx.adapter, ctx.fs, sheet.locale);
+  const baseline = baselineFor(lock, sheet.locale);
+  const { summary, accepted, withheld } = importLocale({
+    sheet,
+    source: ctx.source,
+    target,
+    baseline,
+    adapter: ctx.adapter,
+    sourceInvalidIcuKeys: ctx.sourceInvalidIcuKeys
+  });
+  if (ctx.dryRun) {
+    return { summary, lockEntries: {} };
+  }
+  const merged = mergeAccepted(target, accepted);
+  if (accepted.size > 0) {
+    const path = localeFilePath(ctx.cwd, ctx.config.files.pattern, sheet.locale);
+    await ctx.adapter.write(
+      {
+        locale: sheet.locale,
+        namespace: target.namespace,
+        format: ctx.config.format,
+        entries: merged
+      },
+      path
+    );
+  }
+  return { summary, lockEntries: computeLockEntries2(ctx.source, merged, baseline, withheld) };
+}
+async function importWorkbook(input, deps = {}) {
+  const config = input.config;
+  const cwd = input.cwd ?? process.cwd();
+  const dryRun = input.dryRun ?? false;
+  const fs = deps.fs ?? defaultFs;
+  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const source = await readSource(config, cwd, fs, adapter);
+  const workbookPath = path.resolve(cwd, input.workbook);
+  const bytes = await readWorkbookBytes(workbookPath, fs);
+  let data;
+  try {
+    data = await readWorkbook(bytes);
+  } catch (error) {
+    throw new SdkError("SOURCE_INVALID", error.message);
+  }
+  const lockPath = lockFilePath(cwd);
+  let lock = await readLockFile(lockPath, fs);
+  const ctx = {
+    config,
+    cwd,
+    adapter,
+    fs,
+    source: source.resource,
+    sourceInvalidIcuKeys: source.invalidIcuKeys,
+    dryRun
+  };
+  const summaries = [];
+  for (const sheet of data.sheets) {
+    try {
+      const { summary, lockEntries } = await runSheet(ctx, sheet, lock);
+      if (!dryRun) {
+        lock = updateLockLocale(lock, sheet.locale, lockEntries);
+        await writeLockFile(lockPath, lock, fs);
+      }
+      summaries.push(summary);
+    } catch (error) {
+      summaries.push(failureSummary(sheet.locale, error));
+    }
+  }
+  const { succeeded, failed } = partition(summaries);
+  return { dryRun, locales: summaries, succeeded, failed };
 }
 var defaultCreateWatcher = (paths) => {
   const fsWatcher = chokidar.watch([...paths], { persistent: true, ignoreInitial: true });
@@ -1795,8 +2431,11 @@ async function watch(input, deps = {}) {
   return { stop };
 }
 
+exports.DEFAULT_WORKBOOK_PATH = DEFAULT_WORKBOOK_PATH;
 exports.SdkError = SdkError;
 exports.defineConfig = defineConfig;
+exports.exportWorkbook = exportWorkbook;
+exports.importWorkbook = importWorkbook;
 exports.loadConfig = loadConfig;
 exports.translate = translate2;
 exports.verbatraConfigSchema = verbatraConfigSchema;