本文へスキップ
本文へスキップ

ドキュメント / スタートガイド

機械翻訳されたページ

このページは自動翻訳のため、誤りや不自然な表現が含まれている可能性があります。正式な内容は英語版です。英語の原文を読む。

SDK クイックスタート

@verbatra/sdk をインストールし、API キーなしで実行をプレビューし、自分のスクリプトから翻訳し、エラーを処理し、CI にゲートを設けます。

このページを終えると、TypeScript のスクリプトが英語のロケールファイルをドイツ語に翻訳し、何が起きたかを報告し、ロケールが同期しなくなると CI ジョブを失敗させるようになります。必要なのは Node.js ^22.22.0 || >=24 と、約 10 分です。最初の 3 つの手順では 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 がその package.json を 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 レシピを参照してください。

API キーなしで実行をプレビューする

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

ドライランはプロバイダーを生成しないため、API キーが不要で、費用がかからず、何も書き込みません。代わりに estimate: true を渡すと、トークン数または費用の見積もりが得られます。詳しくは実行前に費用を見積もるを参照してください。

翻訳してサマリーを読む

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;
}

プロバイダーは環境変数から API キーを読み込みます。CLI と違い、SDK は .env ファイルを読み込まないため、自分で渡します。各プロバイダーの変数名は API キーは環境変数から読み込むにあります。

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;
}

API キーなしで実行すると PROVIDER_CONSTRUCTION_FAILED が報告され、足りない変数名が示されます。API キーの値は示されません。すべてのコードはエラーコードにあります。

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 でも API キーは不要です。ソース文字列に訳文がない場合、または翻訳後に変更された場合、スクリプトは 1 で終了します。

CommonJS

CommonJS のプロジェクトでは、require("@verbatra/sdk") が同じエクスポートを返します。トップレベルの await は使えないため、呼び出しを async 関数で包みます。

次のステップ

GitHub で編集

このページの内容