跳到正文
跳到正文

文档 / 入门

机器翻译页面

本页面为自动翻译,可能有错误或表述不够自然。内容以英文版本为准。阅读英文原文。

SDK 快速上手

安装 @verbatra/sdk,无需 API 密钥预览一次运行,用自己的脚本翻译,处理错误,并在 CI 中设门禁。

读完本页,你的 TypeScript 脚本就能把英文语言文件翻译成德语,报告运行结果,并在某个语言环境不同步时让 CI 任务失败。你需要 Node.js ^22.22.0 || >=24,大约 10 分钟。前三步不需要 API 密钥。

每一步都是一个完整的脚本,用 node 运行。Node.js 可以直接运行 TypeScript 文件,因此不需要额外的选项。这些脚本使用 import 和顶层 await,所以第一步还会把项目标记为 ES 模块。

步骤

安装 SDK

npm init -y
npm pkg set type=module
npm install --save-dev @verbatra/sdk

在空目录中运行:npm init -y 会创建 package.json,npm pkg set type=module 再把它标记为 ES 模块。在已有的项目中,跳过 npm init -y。如果 pnpm 以 ERR_PNPM_IGNORED_BUILDS 退出,见安装。

添加源文件和配置

locales/en.json
{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}
verbatra.config.ts
import { defineConfig } from "@verbatra/sdk";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de"],
  format: "i18next-json",
  files: { pattern: "locales/{locale}.json" },
  provider: { id: "gemini", options: { model: "gemini-2.5-flash", maxOutputTokens: 4096 } },
});

loadConfig 会从工作目录找到这个文件并校验它。选择技术栈给出了各框架对应的 format,提供商列出了所有提供商及其选项。要完全跳过这个文件,把同样的对象作为 configOverride 传入,见 SDK 实用示例。

不用密钥预览运行

preview.ts
import { loadConfig, translate } from "@verbatra/sdk";

const config = await loadConfig();
const preview = await translate({ config, dryRun: true });

for (const locale of preview.locales) {
  console.log(`${locale.locale}: would translate ${locale.translated.join(", ")}`);
}
node preview.ts
输出
de: would translate cart.empty, greeting

试运行不会构造提供商,因此不需要密钥,不产生花费,也不写入任何内容。改传 estimate: true 可以得到 token 或费用数字,见运行前估算费用。

翻译并查看摘要

translate.ts
import { loadConfig, translate } from "@verbatra/sdk";

const config = await loadConfig();
const summary = await translate({
  config,
  onProgress: (event) => {
    if (event.type === "locale-finished") console.log(`${event.locale}: ${event.translated} keys`);
  },
});

const { succeeded, partial, failed, usage } = summary;
console.log(`${succeeded.length} ok, ${partial.length} partial, ${failed.length} failed`);
if (usage !== undefined) {
  console.log(`tokens: ${usage.inputTokens} in, ${usage.outputTokens} out`);
}

for (const locale of summary.locales) {
  if (locale.status === "failed") {
    console.error(`${locale.locale}: ${locale.error?.code} ${locale.error?.message}`);
    continue;
  }
  for (const entry of locale.needsReview) {
    console.warn(`review ${locale.locale}/${entry.key}: ${entry.reasons.join(", ")}`);
  }
}

if (failed.length > 0 || partial.length > 0) {
  process.exitCode = 1;
}

提供商从环境变量读取它的密钥,而且与 CLI 不同,SDK 不会加载 .env 文件,所以要自己传入。每个提供商对应的变量见提供商。

node --env-file=.env translate.ts

locales/de.json 现在包含两个键,{{name}} 完好无损。状态为 partial 的语言环境写入时仍缺少一些键,所以脚本遇到它时,会像遇到 failed 一样失败。各语言环境的问题以数据的形式出现在摘要中;只有影响整次运行的问题才会抛出。translate 列出了其他所有选项。

处理错误

影响整次运行的问题会抛出 SdkError。根据它稳定的 code 分支处理,并打印 errorHint 给出的下一步操作。

safe-translate.ts
import { errorHint, loadConfig, SdkError, translate } from "@verbatra/sdk";

try {
  const summary = await translate({ config: await loadConfig() });
  console.log(`${summary.succeeded.length} locales translated`);
} catch (error) {
  if (!(error instanceof SdkError)) {
    throw error;
  }
  switch (error.code) {
    case "CONFIG_NOT_FOUND":
      console.error(`${error.code}: ${error.message} (searched from ${process.cwd()} upward)`);
      break;
    case "PROVIDER_CONSTRUCTION_FAILED":
      console.error(`${error.code}: the provider could not be built, most often for a missing key`);
      break;
    default:
      console.error(`${error.code}: ${error.message}`);
  }
  const hint = errorHint(error);
  if (hint !== undefined) {
    console.error(`next: ${hint}`);
  }
  process.exitCode = 2;
}

不设置密钥运行它,会报告 PROVIDER_CONSTRUCTION_FAILED 并指出缺少的变量,绝不会给出密钥的值。所有错误码见错误码。

用 check 在 CI 中设门禁

check.ts
import { check, loadConfig } from "@verbatra/sdk";

const summary = await check({ config: await loadConfig() });

for (const locale of summary.locales) {
  console.log(`${locale.locale}: ${locale.missing} missing, ${locale.stale} stale`);
}

if (!summary.inSync) {
  process.exitCode = 1;
}
node check.ts

check 不调用任何提供商,也不写入任何内容,因此在 CI 中不需要密钥。源字符串没有译文,或在翻译之后又有更改时,脚本以 1 退出。

CommonJS

在 CommonJS 项目中,require("@verbatra/sdk") 返回相同的导出。那里不能使用顶层 await,所以请把调用包在 async 函数中。

接下来

在 GitHub 上编辑

本页内容