---
title: "Verbatra：変更されたキーだけを翻訳する i18n CLI"
description: "Verbatra はオープンソースの i18n CLI と SDK です。ロケールファイルの欠落しているキーと変更されたキーを見つけ、自分の API キーでそのキーだけを翻訳します。"
---

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

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

- [はじめる](https://verbatra.kreitz-webdev.de/ja/docs/quickstart.md)
- [ほかのツールと比較](https://verbatra.kreitz-webdev.de/ja#compare)

```sh
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

[すべてのフォーマット](https://verbatra.kreitz-webdev.de/ja/docs/formats.md)

### プロバイダー

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

[すべてのプロバイダー](https://verbatra.kreitz-webdev.de/ja/docs/providers.md)

## ロックファイル

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

- **編集**: ソースファイルの 2 件の値を変更します。
- **比較**: Verbatra はすべてのキーのハッシュを計算し、ロックファイルと比較します。記録されたハッシュのうち 2 件が一致しなくなりました。
- **送信**: プロバイダーに送るのは、この 2 件のキーだけです。残りの 12 件は送りません。

**en.json** 2 件変更

```json
{
  …ほか 12 件、変更なし
  "checkout": {
    "title": "Review and checkout", 変更あり
    "pay": "Pay and place order" 変更あり
  }
}
```

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

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

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

**verbatra translate** 2 translated, 12 unchanged

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

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

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

gemini-2.5-flash, 2026年11月13日 生成
verbatra.lock.json：2 件のハッシュを更新しました。

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

すべての候補訳は、ファイルに届く前に整合性ゲートを通ります。 [docs/translation-safety](https://verbatra.kreitz-webdev.de/ja/docs/translation-safety.md)

- **候補訳**: profile.greeting を変更しました（en.json）。プロバイダーは訳文を返しましたが、{name} が抜けています。
- **拒否**: ゲートは候補訳をソースと比較して拒否します。ファイルには手を加えません。
- **古いまま**: キーは古いままなので、チェックは引き続き失敗します。

**profile.greeting** gemini-2.5-flash

**en.json** 変更あり

```text
- "Welcome back, {name}!"
+ "Good to see you, {name}!"
```

**de** プロバイダーの回答

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

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

**verbatra translate** 未書き込み 1 integrity-withheld

```text
$ 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** 未変更

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

**verbatra check** exit 1

```text
$ 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** 未変更

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

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

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

## コマンド: 翻訳の作業全体に対応

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

### ソースから抽出する

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

[`verbatra extract`](https://verbatra.kreitz-webdev.de/ja/docs/cli/extract.md)

**verbatra extract** 2 件の新しいキー

```text
$ 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
```

### 型付きキー

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

[`verbatra types`](https://verbatra.kreitz-webdev.de/ja/docs/cli/types.md)

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

```text
$ npx @verbatra/cli types
verbatra types
  14 keys declared, 1 of them taking arguments, from messages/en.json
  wrote verbatra-types.d.ts
```

```ts
export interface VerbatraMessages {
  …ほか 8 件
  "profile.greeting": { readonly "name": VerbatraArgument };
  …ほか 3 件
  "checkout.title": VerbatraNoArguments;
  "checkout.pay": VerbatraNoArguments;
}
```

### 費用が発生する前に確認する

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

[`verbatra doctor`](https://verbatra.kreitz-webdev.de/ja/docs/cli/doctor.md)

**verbatra doctor** API キー不要

```text
$ 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)
```

### 開発中は監視する

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

[`verbatra watch`](https://verbatra.kreitz-webdev.de/ja/docs/cli/watch.md)

**verbatra watch** 保存のたびに

```text
$ 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...
```

### 人に受け渡す

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

[`verbatra export`](https://verbatra.kreitz-webdev.de/ja/docs/cli/export.md)

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

```text
$ npx @verbatra/cli export --format csv
verbatra export -> verbatra-translations
  de: 2 rows
2 rows across 1 locale
```

| Key | Source | Status | Translation |
| --- | --- | --- | --- |
| checkout.pay | Pay and place order | changed | 翻訳者が入力 |
| checkout.title | Review and checkout | changed | 翻訳者が入力 |

### Studio でレビューする

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

[`verbatra studio`](https://verbatra.kreitz-webdev.de/ja/docs/cli/studio.md)

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

## 結果: どこに聞いても、答えは同じ

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

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

```text
"profile.greeting": "deb45ffcf3548530", stale
```

### CLI

```text
$ 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)
```

[docs/cli/check](https://verbatra.kreitz-webdev.de/ja/docs/cli/check.md)

### Studio

| Locale | Coverage | Missing | Stale | Up to date |
| --- | --- | --- | --- | --- |
| de | 93% 13 / 14 keys | 0 | 1 | 13 |

[docs/cli/studio](https://verbatra.kreitz-webdev.de/ja/docs/cli/studio.md)

### SDK

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

```sh
npm install --save-dev @verbatra/sdk
```

[docs/sdk/inspect](https://verbatra.kreitz-webdev.de/ja/docs/sdk/inspect.md)

### MCP サーバー

プロバイダーを呼び出さない

```text
status.check({})
{ "inSync": false, "locales": [
  { "locale": "de", "missing": 0,
    "stale": 1, "upToDate": 13, ... }
] }
```

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

[docs/cli/mcp](https://verbatra.kreitz-webdev.de/ja/docs/cli/mcp.md)

## 代替手段: Verbatra と他ツールの比較

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

Verbatra と Crowdin、Tolgee、Lingo.dev、手作業の流れの比較

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

最終確認日 2026年11月16日

出典:

- **ベンダーのアカウントなしで使える**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/config/provider-config.ts> <https://github.com/verbatra/verbatra/blob/main/packages/ai-providers/src/env.ts>
  - Crowdin: <https://crowdin.github.io/crowdin-cli/> <https://github.com/crowdin/crowdin-cli>
  - Tolgee: <https://docs.tolgee.io/tolgee-cli/usage> <https://docs.tolgee.io/platform/self_hosting/licensing>
  - Lingo.dev: <https://lingo.dev/en/docs/cli>
- **自分のプロバイダーキーを使う**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/ai-providers/src/env.ts>
  - Crowdin: <https://support.crowdin.com/crowdin-ai/> <https://support.crowdin.com/machine-translation/>
  - Tolgee: <https://docs.tolgee.io/platform/projects_and_organizations/llm-providers> <https://docs.tolgee.io/platform/translation_process/machine_translation>
  - Lingo.dev: <https://lingo.dev/pricing> <https://lingo.dev/en/docs/platform/llm-models>
- **変更されたキーだけを翻訳する**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/flow/locale-run.ts>
  - Crowdin: <https://support.crowdin.com/pre-translation/>
  - Tolgee: <https://docs.tolgee.io/platform/projects_and_organizations/machine-translation-settings>
  - Lingo.dev: <https://lingo.dev/en/docs/cli/ci>
- **翻訳が欠落または古いと CI を失敗させる**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/cli/src/run.ts>
  - Crowdin: <https://crowdin.github.io/crowdin-cli/commands/crowdin-status>
  - Tolgee: <https://github.com/tolgee/tolgee-cli/tree/main/src/commands> <https://raw.githubusercontent.com/tolgee/tolgee-cli/main/src/commands/sync/compare.ts>
  - Lingo.dev: <https://lingo.dev/en/docs/cli/ci>
- **翻訳後にプレースホルダーと ICU を検査する**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/core/src/placeholder/integrity.ts> <https://github.com/verbatra/verbatra/blob/main/packages/sdk/src/flow/integrity-gate.ts>
  - Crowdin: <https://support.crowdin.com/project-settings/qa-checks/>
  - Tolgee: <https://docs.tolgee.io/platform/translation_process/qa_checks>
  - Lingo.dev: <https://lingo.dev/en/docs/platform/ai-reviewers>
- **翻訳者向けの Web エディター**
  - Verbatra: <https://github.com/verbatra/verbatra/blob/main/packages/studio/src/server/create-studio-server.ts>
  - Crowdin: <https://support.crowdin.com/online-editor/>
  - Tolgee: <https://docs.tolgee.io/platform/>
  - Lingo.dev: <https://lingo.dev/en/docs/api/pipeline/human-review>

## よくある質問: Verbatra を導入する前に

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

### Verbatra は無料ですか？

はい。[MIT ライセンス](https://github.com/verbatra/verbatra/blob/main/LICENSE)のオープンソースで、無料です。費用は変更されたキーのぶんのプロバイダー料金だけで、[実行前に費用を見積もる](https://verbatra.kreitz-webdev.de/ja/docs/estimating-cost.md)と規模を先に確認できます。

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

Anthropic、OpenAI、Gemini、DeepL、Google Cloud Translation、OpenCode、OpenAI-compatible、LibreTranslate に対応しています。`provider` に 1 つ指定します（人だけが翻訳する場合は `none`）。詳しくは[プロバイダー](https://verbatra.kreitz-webdev.de/ja/docs/providers.md)を参照してください。

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

送り先は、コマンドが翻訳するときの、設定したプロバイダーだけです。テレメトリはありません。API キーは環境変数にだけ置き、各プロバイダーが受け取る内容は[データの取り扱いとプライバシー](https://verbatra.kreitz-webdev.de/ja/docs/data-handling.md)に載っています。

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

はい。`verbatra check` は API キー不要で、ロケールに欠落しているキーや古くなったキーがある間は終了コード 1 で終了します。[GitHub Action](https://verbatra.kreitz-webdev.de/ja/docs/github-action.md) は、これを pull request で実行します。

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

ホスト型のプラットフォームではなく、手元のコミット済みファイルに対して動く CLI です。[比較表](https://verbatra.kreitz-webdev.de/ja#compare)では、ほかのツールが優れている点も含めて照らし合わせています。

関連ドキュメント:

- [クイックスタート](https://verbatra.kreitz-webdev.de/ja/docs/quickstart.md)
- [翻訳の安全性](https://verbatra.kreitz-webdev.de/ja/docs/translation-safety.md)
- [比較表](https://verbatra.kreitz-webdev.de/ja#compare)

## まずドライランから

トークンを消費する前に

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

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

- [npm の来歴証明](https://www.npmjs.com/package/@verbatra/cli)
- [MIT ライセンス](https://github.com/verbatra/verbatra/blob/main/LICENSE)
- [CLI はテレメトリを送信しません](https://verbatra.kreitz-webdev.de/ja/docs/data-handling.md)
- [カバレッジゲート 90%](https://codecov.io/gh/verbatra/verbatra)
- [CI ワークフロー](https://github.com/verbatra/verbatra/actions/workflows/ci.yml)
