@verbatra/sdk 0.2.0 → 0.2.1

package/README.md

@@ -16,7 +16,7 @@
 
 ## Description
 
-`@verbatra/sdk` is the engine behind verbatra: load and validate a config, run the one-shot translate flow over every target locale, or watch the source and re-translate on each change. The [`@verbatra/cli`](https://github.com/mariokreitz/verbatra/tree/main/packages/cli) command is a thin wrapper over this package.
+`@verbatra/sdk` is the engine behind verbatra: load and validate a config, run the one-shot translate flow over every target locale, watch the source and re-translate on each change, or export and import an Excel workbook for manual translation. The [`@verbatra/cli`](https://github.com/mariokreitz/verbatra/tree/main/packages/cli) command is a thin wrapper over this package.
 
 ## Requirements
 
@@ -70,7 +70,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`, and `ngx-translate-json`. 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`, and `ngx-translate-json`. The optional `glossary` (a term map) and `tone` (`"formal"`, `"informal"`, or `"neutral"`) refine the output. 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`).
 
 ## API reference
 
@@ -107,6 +107,28 @@ const controller = await watch({
 process.on("SIGINT", () => void controller.stop());
 ```
 
+### `exportWorkbook(input): Promise<ExportWorkbookResult>`
+
+Exports the strings that need translating into a styled Excel workbook for a human translator. `input` is `{ config, cwd?, out?, locales?, includeUnchanged? }`. By default it writes the missing and changed strings for every target locale to `verbatra-translations.xlsx`; `out` overrides the path, `locales` narrows which target locales are exported, and `includeUnchanged: true` also exports already up-to-date strings. Resolves to an `ExportWorkbookResult` with the written `path` and a per-locale row count.
+
+### `importWorkbook(input): Promise<RunSummary>`
+
+Imports a filled workbook back into the locale files, running the same placeholder and ICU checks as `translate`. `input` is `{ config, workbook, cwd?, dryRun? }`. With `dryRun: true` it validates and reports without writing locale files or updating the lock. Resolves to a `RunSummary`, the same shape `translate` returns.
+
+```ts
+import { exportWorkbook, importWorkbook, loadConfig } from "@verbatra/sdk";
+
+const config = await loadConfig();
+
+// Export the strings that need translating to an Excel workbook.
+const { path } = await exportWorkbook({ config });
+
+// ...a human fills the Translation column, then import the file back.
+const summary = await importWorkbook({ config, workbook: path });
+```
+
+See [Manual translation](https://verbatra.kreitz-webdev.de/docs/manual-translation) for the full round-trip and the workbook layout.
+
 ## Errors and results
 
 The SDK throws a single structured error type, `SdkError`, for whole-run failures such as a missing or invalid config or an unreadable source file. It carries a stable `code` and never contains an API key. Per-locale failures do not throw: they are recorded on the `RunSummary` so one failing locale never aborts the others.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verbatra/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Programmatic API to automate i18n translation and keep your locale files in sync across languages with AI and machine-translation providers.",
   "keywords": [
@@ -31,7 +31,7 @@
     "url": "git+https://github.com/mariokreitz/verbatra.git",
     "directory": "packages/sdk"
   },
-  "homepage": "https://github.com/mariokreitz/verbatra/tree/main/packages/sdk",
+  "homepage": "https://verbatra.kreitz-webdev.de",
   "bugs": {
     "url": "https://github.com/mariokreitz/verbatra/issues"
   },
@@ -71,15 +71,15 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@types/node": "22.19.21",
+    "@types/node": "26.0.0",
     "@vitest/coverage-v8": "4.1.8",
     "tsup": "8.5.1",
     "typescript": "6.0.3",
     "vitest": "4.1.8",
-    "@verbatra/ai-providers": "0.1.0",
-    "@verbatra/core": "0.1.0",
     "@verbatra/exchange": "0.2.0",
     "@verbatra/format-adapters": "0.2.0",
+    "@verbatra/ai-providers": "0.1.0",
+    "@verbatra/core": "0.1.0",
     "@verbatra/config": "0.0.0"
   },
   "scripts": {