本文へスキップ

翻訳するのは変更された部分だけ

Verbatra はすべてのキーのハッシュをロックファイルに記録し、変更されたキーだけをプロバイダーに送り、ドリフトがあると CI を失敗させます。

はじめる
npm i -D @verbatra/cli

すでに使っているロケールファイルとプロバイダーに対応

ファイルフォーマット

  • i18next JSON
  • vue-i18n JSON
  • next-intl JSON
  • ngx-translate JSON
  • XLIFF
  • YAML
  • Flutter ARB
  • Java/Spring .properties
  • Apple .strings
  • Xcode String Catalog
  • Android strings.xml
  • gettext .po/.pot
  • INI
  • .NET .resx

プロバイダー

  • Anthropic
  • OpenAI
  • Gemini
  • DeepL
  • Google Cloud Translation
  • OpenCode
  • OpenAI-compatible
  • LibreTranslate

ロックファイル

二つのキーが変更され、二つを送信

編集ソースファイルの 2 件の値を変更します。

en.json 2 件変更

{
…ほか 12 件、変更なし
"checkout": {
"title": "Review and checkout", 変更あり
"pay": "Pay and place order" 変更あり
}
}
比較Verbatra はすべてのキーのハッシュを計算し、ロックファイルと比較します。記録されたハッシュのうち 2 件が一致しなくなりました。

verbatra.lock.json 2 stale, 12 up-to-date

{
"version": 1,
"locales": {
"de": {
…ほか 4 件、変更なし
"cart.total": "692deda3edfe75da",
"checkout.pay": "bcdca4b40874a53a", 古い
"checkout.title": "f0eeada9213af138", 古い
"errors.notFound": "427078dedd81b2ce",
…ほか 6 件、変更なし
}
}
}

古い(stale)とは、記録されたハッシュが現在の en.json の値のハッシュと一致しないことです。残りの 12 件は一致しています。

送信プロバイダーに送るのは、この 2 件のキーだけです。残りの 12 件は送りません。

verbatra translate 2 translated, 12 unchanged

$ npx @verbatra/cli translate
  de: 2 translated, 12 unchanged

de.json 事前生成(リアルタイムではありません)

{
…ほか 12 件、変更なし
"checkout": {
"title": "Überprüfen und zur Kasse gehen", 変更あり
"pay": "Bezahlen und Bestellung aufgeben" 変更あり
}
}

gemini-2.5-flash,
verbatra.lock.json:2 件のハッシュを更新しました。

ゲート

プロバイダーが誤っても、何も書き込まれません

すべての候補訳は、ファイルに届く前に整合性ゲートを通ります。 docs/translation-safety

候補訳profile.greeting を変更しました(en.json)。プロバイダーは訳文を返しましたが、{name} が抜けています。

profile.greeting gemini-2.5-flash

en.json 変更あり

"Welcome back, {name}!"
"Good to see you, {name}!"

de プロバイダーの回答

"Schön, Sie zu sehen!" {name} 欠落

まだ検証も書き込みもしていません。

拒否ゲートは候補訳をソースと比較して拒否します。ファイルには手を加えません。

verbatra translate 未書き込み 1 integrity-withheld

$ npx @verbatra/cli translate
  de: failed, 0 translated, 13 unchanged, 1 integrity-withheld
    integrity-withheld:
      profile.greeting: placeholder (-{name})
0 succeeded, 0 partial, 1 failed

de.json 未変更

"profile": {
"greeting": "Willkommen, {name}!",
...
古いままキーは古いままなので、チェックは引き続き失敗します。

verbatra check exit 1

$ npx @verbatra/cli check
  de: 0 missing, 1 stale, 13 up-to-date (out of sync)
out of sync (run verbatra translate to update)

de.json 未変更

"profile": {
"greeting": "Willkommen, {name}!",
...

de.json は前の値のままです。キーは古いままで、次の実行で再試行されます。

ロックファイルは一つ。すべてのコマンドがそれを読みます。

コマンド

翻訳の作業全体に対応

ソースコードの最初の文字列から、本番に出るレビュー済みの訳文まで。

  1. verbatra extract

    verbatra extract 2 件の新しいキー

    $ npx @verbatra/cli extract --dry-run
    verbatra extract
      1 file scanned, 2 keys already present
      would add 2 keys to messages/en.json
      new keys (2):
        checkout.giftNote  src/Checkout.tsx:8
        checkout.backToCart  src/Checkout.tsx:10
    dry run, nothing written

    would add 2 keys to messages/en.json

    コードから翻訳の呼び出しを探し、誰かが翻訳する前に、新しいキーをソースロケールに追加します。

    docs/cli/extract
  2. verbatra types

    verbatra-types.d.ts 14 件のキーを宣言済み

    $ npx @verbatra/cli types
    verbatra types
      14 keys declared, 1 of them taking arguments, from messages/en.json
      wrote verbatra-types.d.ts
    export interface VerbatraMessages {
      …ほか 8 件
      "profile.greeting": { readonly "name": VerbatraArgument };
      …ほか 3 件
      "checkout.title": VerbatraNoArguments;
      "checkout.pay": VerbatraNoArguments;
    }

    14 keys declared, 1 of them taking arguments, from messages/en.json

    キーとメッセージ引数の TypeScript 宣言を生成するので、キーのタイプミスはビルドの失敗になります。

    docs/cli/types
  3. verbatra doctor

    verbatra doctor API キー不要

    $ npx @verbatra/cli doctor
    verbatra doctor
      [ok  ] Configuration: Loaded .verbatrarc.json.
      [ok  ] Format adapter: Format "next-intl-json" resolves to an adapter.
      [ok  ] Provider: Provider "gemini" resolves to a factory.
      [fail] API key environment variable: The GEMINI_API_KEY environment variable is not set.
             fix: Set GEMINI_API_KEY in the environment, or, with the CLI, in a .env file in the project directory.
      …ほかのチェックもすべて合格
    1 problem found (run verbatra doctor again after fixing it)
    $ npx @verbatra/cli translate --dry-run
    verbatra translate (dry run)
      de: 2 would translate, 12 unchanged
    1 succeeded, 0 partial, 0 failed (dry run: nothing written)

    de: 2 would translate, 12 unchanged

    doctor は API キーなしで構成を確認し、見積もりは費用が発生する前に実行の規模を示します。

    docs/cli/doctor
  4. verbatra watch

    verbatra watch 保存のたびに

    $ npx @verbatra/cli watch
    verbatra: watching en (messages/{locale}.json); running initial translation
    verbatra: translating de
    verbatra: de batch 1/1
    verbatra: de: writing
    verbatra: de done, 2 translated
    verbatra: run finished, 1 locale processed
    verbatra translate
      de: 2 translated, 12 unchanged
    1 succeeded, 0 partial, 0 failed
    verbatra: waiting for changes...

    de: 2 translated, 12 unchanged

    開発中に監視プロセスを動かしておくと、ソースロケールを変更するたびに、保存と同時に翻訳されます。

    docs/cli/watch
  5. verbatra export

    verbatra-translations/de.csv 翻訳待ち 2 行

    $ npx @verbatra/cli export --format csv
    verbatra export -> verbatra-translations
      de: 2 rows
    2 rows across 1 locale
    KeySourceStatusTranslation
    checkout.payPay and place orderchanged翻訳者が入力
    checkout.titleReview and checkoutchanged翻訳者が入力

    de: 2 rows

    翻訳者向けに Excel ブック、CSV、TSV、XLIFF をエクスポートし、あとでインポートして戻します。インポートした値は、以降の機械翻訳の実行から保護されます。

    docs/cli/export
  6. verbatra studio

    verbatra studio 実際のスクリーンショット

    プロジェクトを扱うローカルのダッシュボード。全ロケールを閲覧し、レビューキューを処理し、値をその場で編集できます。

    docs/cli/studio

結果

どこに聞いても、答えは同じ

どのインターフェースも同じロックファイルを読むため、profile.greeting が拒否されている状態では、どこで確認しても、ドイツ語は古い 1 件、最新 13 件です。

verbatra.lock.json 1 stale, 13 up-to-date

"profile.greeting": "deb45ffcf3548530", stale

CLI

verbatra check
$ npx @verbatra/cli check
verbatra check
  de: 0 missing, 1 stale, 13 up-to-date (out of sync)
out of sync (run verbatra translate to update)

Studio

Locales
ロケールの対応率
LocaleCoverageMissingStaleUp to date
de93% 13 / 14 keys0113

SDK

check()
import { check } from "@verbatra/sdk";
const summary = await check({ config });
summary.locales[0];
// { locale: "de", missing: 0,
//   stale: 1, upToDate: 13,
//   inSync: false, ... }

npm install --save-dev @verbatra/sdk

MCP サーバー

プロバイダーを呼び出さない
status.check({})
{ "inSync": false, "locales": [
  { "locale": "de", "missing": 0,
    "stale": 1, "upToDate": 13, ... }
] }

claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp

docs/cli/mcp

代替手段

Verbatra と他ツールの比較

翻訳ワークフローを左右するポイントについて、チームがよく比較するツールごとの答えをまとめました。

Verbatra と Crowdin、Tolgee、Lingo.dev、手作業の流れの比較
質問VerbatraCrowdinTolgeeLingo.dev手作業の流れ
ベンダーのアカウントなしで使えるはいいいえ一部いいえはい
自分のプロバイダーキーを使うはいはい一部一部はい
変更されたキーだけを翻訳するはい一部一部はいいいえ
翻訳が欠落または古いと CI を失敗させるはいはいいいえはいいいえ
翻訳後にプレースホルダーと ICU を検査するはいはいはい一部いいえ
翻訳者向けの Web エディター一部はいはい一部いいえ

最終確認日 2026年11月16日

よくある質問

Verbatra を導入する前に

短い回答を並べ、それぞれに詳しいドキュメントへのリンクを付けています。

Verbatra は無料ですか?

はい。MIT ライセンス (新しいタブで開きます)のオープンソースで、無料です。費用は変更されたキーのぶんのプロバイダー料金だけで、実行前に費用を見積もると規模を先に確認できます。

Verbatra はどの翻訳プロバイダーに対応していますか?

Anthropic、OpenAI、Gemini、DeepL、Google Cloud Translation、OpenCode、OpenAI-compatible、LibreTranslate に対応しています。provider に 1 つ指定します(人だけが翻訳する場合は none)。詳しくはプロバイダーを参照してください。

Verbatra は文字列や API キーをどこかに送りますか?

送り先は、コマンドが翻訳するときの、設定したプロバイダーだけです。テレメトリはありません。API キーは環境変数にだけ置き、各プロバイダーが受け取る内容はデータの取り扱いとプライバシーに載っています。

翻訳が欠けているとき、Verbatra は pull request を失敗させられますか?

はい。verbatra check は API キー不要で、ロケールに欠落しているキーや古くなったキーがある間は終了コード 1 で終了します。GitHub Action は、これを pull request で実行します。

Verbatra はほかの i18n ツールと何が違いますか?

ホスト型のプラットフォームではなく、手元のコミット済みファイルに対して動く CLI です。比較表では、ほかのツールが優れている点も含めて照らし合わせています。

トークンを消費する前に

まずドライランから

この手順は、すでにロケールファイルがあるプロジェクト向けで、どちらのステップも API キーは不要です。

npx @verbatra/cli init
npx @verbatra/cli translate --dry-run