ドキュメント / スタートガイド
機械翻訳されたページ
AI エージェントで verbatra をセットアップする
i18n の構成がすでにあるプロジェクトに verbatra を追加するための、AI コーディングエージェント向けの短いプロンプトです。費用が発生する前に人が確認します。
このページは、ロケールファイルがすでにコミットされているプロジェクト向けです。上の AI エージェント向けのプロンプトを Claude Code、Codex、Gemini CLI、Cursor など、シェルコマンドを実行できるエージェントに貼り付けます。エージェントは以下の手順に従い、次の 3 つを確認します。
- 使用するプロバイダー:プロジェクトから明らかな場合を除きます。
- API キー:エージェントは
.envの変数を空のままにします。値は人が入力し、エージェントが API キーを尋ねることはありません。 - 実行の許可:最初に
translateを本番実行する前に確認します。すぐに費用が発生するためです。
エージェントが従う手順
エージェント向け:手順を順番に実行します。手順 6 の停止は省略しないでください。
1. 既存の構成を調べる
何かを変更する前に、package.json で i18n ライブラリ(i18next、vue-i18n、next-intl など)とロケールファイルを探します。ソースロケール、すでにあるすべてのターゲットロケール、{locale} プレースホルダーを含むパスのパターン(locales/{locale}.json など)を控えます。技術スタックを選ぶは、各技術スタックのフォーマット ID とレイアウトを示します。フォーマットは、あらかじめ存在している必要があるファイルを説明します。i18n ライブラリを使わないプレーンな JSON の場合:{{name}} プレースホルダーなら i18next-json、波括弧 1 つの {name} なら vue-i18n-json です。
2. CLI をインストールする
npm install --save-dev @verbatra/clipnpm、yarn、bun でも使えます。インストールスクリプトは承認しません。pnpm approve-builds でも npm の allowScripts でも同じです。verbatra にはインストールスクリプトは不要です。
3. 設定ファイルとエージェント用ファイルを作成する
npx @verbatra/cli init --provider <provider> --yes --json --agentプロジェクトから明らかな場合を除き、使用するプロバイダーを人に尋ねます。人が同意していないサービスで費用が発生するプロバイダーは選ばないでください。init に API キーの値を渡すことも絶対にしません。プロバイダーに ID の一覧があります。none は機械翻訳をオフにします。init はフォーマット、パスのパターン、ロケールを検出し、JSON のエンベロープ(envelope)を 1 つ出力します。対話式の質問はしません。--agent を付けると、AGENTS.md に verbatra のセクションを書き込みます。指示ファイルが CLAUDE.md だけの場合や、CLAUDE.md にすでに verbatra のセクションがある場合は、CLAUDE.md に書き込みます。さらに、課金をオフにした verbatra MCP サーバーを、検出した各クライアントの設定に書き込みます。Claude Code を検出した場合、またはクライアントを 1 つも検出しなかった場合は、Claude Code の .mcp.json に書き込みます。書き込んだファイルは result.agent.clients に一覧されます。
| 終了コードとエラーコード | 対処 |
|---|---|
0 | result.config を手順 1 の内容と照らし合わせます。まず default と表示されている result.sources のエントリから確認します。result.config.files.localeStyle は、ファイルがロケールを記述どおりに表記していない場合にだけ現れます。誤りがあれば、正しい --format、--path、--source、--targets と --force を付けて再実行します。 |
2、FORMAT_ または LAYOUT_ | candidates から選び、--format または --path を付けて再実行します。名前空間ごとのファイルが並んでいる場合は、止まって人に確認します。1 つの設定ファイルで扱えるファイルパターンは 1 つだけだからです。 |
2、MISSING_ | まだ必要なオプションがすべてメッセージに示されます。 |
2、CONFIG_ | 既存の設定ファイルが使うプロバイダーを人に伝え、確認を待ちます。その後 npx @verbatra/cli init --agent --json を実行します。設定ファイルはそのままにして、エージェント用ファイルだけを追加します。--force を付ける前に確認してください。 |
すべてのオプションは init に記載しています。
4. API キーは人に任せる
プロバイダーが none の場合は、この手順を省略します。API キーの変数は result.apiKeyEnvVar です。CONFIG_ の後は null になるため、npx @verbatra/cli doctor --json で失敗している api-key チェックから変数名を取ります。.env.example を .env にコピーします。init が例を書き込まなかった場合は、.env を新しく作成します。そこに変数名を値なしで書き、人に入力を依頼します。API キーの値を書いたり、作り出したり、尋ねたりしないでください。入力を待たずに先へ進みます。
5. 費用をかけずに構成を確認する
npx @verbatra/cli doctor --json
npx @verbatra/cli check --json
npx @verbatra/cli diff --json
npx @verbatra/cli translate --dry-run --jsonこれらはいずれも、プロバイダーを呼び出さず、API キーを必要とせず、ファイルを書き込みません。失敗している doctor のチェックのうち、verbatra.config.ts で直せるものはすべて直します。api-key チェックは人が API キーを設定して初めて通るため、繰り返し直そうとしないでください。check や diff では、最初の実行の前に終了コード 1(同期していない)が出るのは想定どおりです。構成の問題を示すのは終了コード 2 だけです。プロバイダーが none の場合、翻訳者に任せるキーが残っていると、translate --dry-run は終了コード 3 で終了します。翻訳されるのはターゲットにないキーだけで、空文字列は存在するものとして扱われます。そのため、ダミー値として "" を入れたキーを削除する前に確認します。
6. 止まって確認を求める
ロケールごとの未処理のキーの数と、translate --dry-run が報告した内容を要約してから、止まります。実際の実行はすぐに費用が発生し、実行前に確認する対話式の質問もありません。人からの明確な許可を待ちます。人から求められない限り、--prune は使わないでください。
7. 許可を得てから翻訳する
npx @verbatra/cli translate --jsonサマリーの succeeded、partial、failed の一覧を報告します。partial または failed のロケールでは、成功した分が残ります。
8. コミットして接続する
次のファイルをコミットします。verbatra.config.ts、存在する場合は .env.example、手順 3 の指示ファイルとクライアントの設定ファイル、verbatra.lock.json、実行によって書き込まれた後の verbatra.provenance.json、翻訳済みのロケールファイルです。.env、.env.local、.verbatra-local/、verbatra.cache.json は絶対にコミットしないでください。.gitignore がこれらを対象にしていることを確認します。
続けて、クライアントを再起動し、プロジェクトの verbatra サーバーを承認するよう人に伝えます。Claude Code では、verbatra プラグインを重ねてインストールしないでください。サーバーが二重に登録されます。接続は claude mcp list で確認できます。init が検出しなかったクライアントには、MCP クライアントを接続するにあるエントリを 1 つ追加します。
次のステップ
MCP クライアントを接続する
Claude Code 以外の各クライアントに必要な 1 つのエントリと、エージェントに課金を許可する方法です。
エージェントとスクリプト向けのレシピ
このプロンプトのコマンドが前提にしている --json のエンベロープと終了コードです。独自のエージェントループを作るときに使います。
ブラウザーエージェントで Studio を操作する
シェルではなくブラウザーのタブから、セットアップ済みのプロジェクトを操作するための別の画面やツールです。
クイックスタート
同じセットアップの手順を、エージェントではなく人向けに書いたものです。
ロックファイルと来歴
このプロンプトが前提にしている、既存プロジェクト導入時の安全な動作の詳細です。