ドキュメント / スタートガイド
機械翻訳されたページ
クイックスタート
CLI をインストールし、設定ファイルを作成して、API キーなしで実行をプレビューし、最初のロケールファイルを翻訳します。
このページを終えると、英語のロケールファイルに対応するドイツ語のファイルができます。プロバイダーが書き、verbatra がチェックしたファイルです。あわせて、以降の実行で変更された箇所だけを翻訳するためのロックファイルもできます。必要なのは Node.js ^22.22.0 || >=24 と、約 10 分の時間です。最初の 4 つのステップには、アカウントも API キーも不要です。
ロケールファイルとコーディングエージェントは、すでにありますか?
AI エージェントで verbatra をセットアップするのプロンプトをエージェントに渡します。エージェントは、プロジェクトにすでにあるロケールファイルをそのまま使って verbatra を導入し、費用が発生する前に止まります。以下の手順は、ゼロから始めるものです。
翻訳したファイルをアプリに読み込むところまで含むクイックスタートが、React、Next.js、Vue、Angular、Flutter 向けに用意されています。
手順
CLI をインストールする
npm install --save-dev @verbatra/cli以下のコマンドは npx を使います。pnpm、yarn、bun では、代わりに pnpm verbatra、yarn verbatra、bun run verbatra を実行します。pnpm が ERR_ で終了した場合は、トラブルシューティングを参照してください。
ソースロケールファイルを追加する
プロジェクトにすでにロケールファイルがある場合は、この手順を飛ばします。ない場合は、次のように作成します。
{
"greeting": "Hello, {{name}}!",
"cart": {
"empty": "Your cart is empty."
}
}設定ファイルを作成する
npx @verbatra/cli init --format i18next-json --provider gemini --yes--format にはファイルフォーマットを指定します。各フレームワークの ID は技術スタックを選ぶにあります。--yes を付けると、対話式の質問を出さずに、init が検出した内容をそのまま使います。省略すると、verbatra init が挙げる対話式の質問に答えられます。
created verbatra.config.ts
created .env.example
created .gitignore (.env, .env.local, .verbatra-local/, verbatra.cache.json)
detected format i18next-json, pattern locales/{locale}.json, locales en (confidence: medium)
next steps:
- Copy .env.example to .env and set GEMINI_API_KEY there. Never commit .env.
- npx @verbatra/cli doctor (Check the setup. It calls no provider and reads no key value.)
- npx @verbatra/cli translate --dry-run (Preview what a run would translate, without calling the provider.)新しい verbatra.config.ts は、en から de へ翻訳します。言語を増やすには、targetLocales にコードを追加します。
API キーなしで実行をプレビューする
npx @verbatra/cli translate --dry-runverbatra: dry run over 1 locale, no provider call
verbatra: de done, 2 would translate
verbatra translate (dry run)
de: 2 would translate, 0 unchanged
1 succeeded, 0 partial, 0 failed (dry run: nothing written)
[ok] dry run done in 0.0s, nothing written
next: verbatra translate (run it for real)これは対話型ターミナルでの表示です。パイプ経由や CI では、各ステップにも専用の行が出力されます。詳しくはターミナル出力を参照してください。ドライランはプロバイダーを生成しないので、API キーは不要で、費用はかからず、何も書き込まれません。verbatra doctor も、同じ方法で構成の残りをチェックします。
翻訳する
cp .env.example .env.env を開き、GEMINI_ の後に API キーを貼り付けます。API キーは必ず環境変数から読み込まれ、CLI は .env.local と .env をそこに読み込みます。API キーがまだない場合、Gemini には無料枠があり、Google AI Studio で API キーを作成できます。ほかのプロバイダーと、その環境変数はプロバイダーに載っています。
npx @verbatra/cli translateverbatra は欠落している 2 件のキーを Gemini に送り、すべての結果をチェックして、ドイツ語のファイルを書き込みます。サマリーは de: 2 translated, 0 unchanged で始まり、実行で使ったトークンが一覧表示されます。表現はモデルによって変わります。たとえば次のようになります。
{
"greeting": "Hallo, {{name}}!",
"cart": {
"empty": "Dein Warenkorb ist leer."
}
}すべてのロケールが同期していることを確認する
npx @verbatra/cli check[ok] checking the locales (0.0s)
verbatra check
de: 0 missing, 0 stale, 2 up-to-date (in sync)
all locales in synccheck はプロバイダーを呼び出さず、ロケールが同期していない状態になるとすぐに終了コード 1 で終了します。そのため、同じコマンドで pull request をゲートで止められます。
ここで起きたこと
locales/de.jsonには、ソースと同じキーが同じ順序で入り、{{name}}も残っています。プレースホルダーが欠けた結果は保留され、書き込まれることはありません。詳しくは翻訳の安全性を参照してください。verbatra.lock.jsonは、各訳文の元になったソース文字列のハッシュを記録します。そのため次回の実行では、新しいキーと変更されたキーだけが送られます。詳しくはロックファイルと来歴を参照してください。verbatra.provenance.jsonは、各値を書いたプロバイダーとモデルを記録します。詳しくは来歴:各値を誰が書いたかを参照してください。verbatra.cache.jsonと.verbatra-local/には、再生成可能な翻訳キャッシュとローカルの実行状態が入っています。initはすでに両方を gitignore に追加しています。詳しくは翻訳キャッシュを参照してください。
ロケールファイル、ロックファイル、来歴ファイルをまとめてコミットします。そうすると、すべてのマシンと CI が同じベースラインと比較できます。
次のステップ
言語を追加する
ターゲットロケールを追加し、1 回の実行で埋めます。
CI で verbatra を実行する
ロケールがドリフトしたら pull request を失敗させます。
実行の仕組み
いま実行したコマンドの裏側で動く処理の流れを説明します。
設定ファイル
verbatra.config.ts に書けるすべての内容を説明します。