ドキュメント / ヘルプ
翻訳が古い可能性があります
よくある質問
verbatra の実行でよくある質問に短く答えます。1 回の実行にかかる費用から、何をコミットすべきかまでを扱います。
短い回答と、詳細を説明しているページへのリンクをまとめています。エラーメッセージについては、トラブルシューティングとエラーコードを参照してください。
費用を抑えるにはどうすればよいですか?
実行は差分のみなので、欠落しているキーと変更されたキーだけがプロバイダーに送られます。変更のないプロジェクトを再実行しても、費用はかかりません。verbatra translate --estimate を使うと、プロバイダーを呼び出さずに実行の規模を見積もれます。--max-tokens または設定ファイルの maxTokens で、上限を設けることもできます。実行前に費用を見積もるを参照してください。
1 回の実行に実際いくらかかりますか?
わずかです。gemini-2.5-flash で 400 件のキーを 3 つのロケールに翻訳すると、約 72,000 トークンになります。これにプロバイダーの現在の単価を掛けて計算します。以降の実行では、変更した文字列の分しか費用がかかりません。実行の規模の見積もり方、各プロバイダーが単価を公開している場所、自分のプロジェクトで見積もりを調整する方法は、実行前に費用を見積もるにあります。
どのプロバイダーから始めればよいですか?
Gemini です。API の無料枠で、費用をかけずにプロジェクト全体を翻訳でき、あとから切り替えるときも id を 1 つ書き換えるだけで済みます。社外秘の文字列は、無料枠に送らないでください。データの取り扱いとプライバシーを参照してください。すべてのプロバイダーの比較は、プロバイダーにあります。
ローカルモデルを使えますか?
はい。openai-compatible プロバイダーを使うと、LM Studio、Ollama、vLLM など、OpenAI の chat API に対応する任意のサーバーに verbatra を向けられます。通常、API キーは不要です。言語モデルをまったく使わない場合は、libretranslate がセルフホストの LibreTranslate サーバーを使います。プロバイダーを参照してください。
verbatra はどの言語に対応していますか?
プロバイダーが対応している言語であれば、pt-BR や zh-Hant のような有効な BCP 47 コードで指定して使えます。DeepL と Google Cloud Translation には固定の言語リストがあり、LLM プロバイダーにはありません。言語とロケールを参照してください。
キーの順序はどのように保たれますか?
既存のキーは位置を保ち、新しいキーはソースの順序で追加されます。そのため、翻訳されたファイルの差分は見やすいままです。フォーマットを参照してください。
訳文にレビューのフラグが付いたのはなぜですか?
レビューのヒューリスティックが、もう一度確認する価値のある点を見つけました。たとえば、訳文がソースと同じ場合です。保留はせずに、フラグだけが付きます。すべての理由コードは、レビューの理由に一覧があります。
verbatra はモノレポで使えますか?
はい。設定ファイルの探索は、作業ディレクトリから上に向かって進み、最も近い .git で止まります。そのため、各パッケージは自分の設定ファイルを見つけ、ルートはルートの設定ファイルを見つけます。ほかの場所を指定するには、--cwd と --config を使います。設定ファイルを参照してください。
何をコミットすればよいですか?
ロケールファイル、verbatra.lock.json、verbatra.provenance.json をコミットします。.env、.env.local、.verbatra-local/、verbatra.cache.json はコミットしません。これらは verbatra init が .gitignore に追加します。ロックファイルと来歴を参照してください。
すべてを翻訳し直すにはどうすればよいですか?
ロケールファイルを削除して、verbatra translate --no-cache を実行します。すると、すべてのキーが欠落として扱われ、プロバイダーに再び送られます。--no-cache を付けない場合は、翻訳メモリにヒットしたキーが、保持している値で埋め直されます。ロックファイルを削除しても、翻訳し直せません。ベースラインがないと、既存の訳文は最新として扱われるためです。1 つのキーだけなら、Studio の再翻訳の操作か retranslateEntry を使います。
CLI を使うには SDK のインストールが必要ですか?
追加の手順は不要です。@verbatra/cli が @verbatra/sdk に依存しているため、一緒にインストールされます。別にインストールする任意のパッケージは、@verbatra/studio と @verbatra/mcp だけです。
API キーはどこに置きますか?
環境変数だけです。CLI は .env.local と .env からも読み込みます。設定ファイルは未知の設定キーを拒否するため、シークレットがコミットされるファイルに入ることはありません。プロバイダーを参照してください。
verbatra は文字列をどこかに送信しますか?
設定したプロバイダーにだけ、それもコマンドが翻訳するときにだけ送信します。テレメトリはありません。provider: { id: "none" } の場合は、何もマシンの外に出ません。データの取り扱いとプライバシーを参照してください。
verbatra doctor は実際に何をチェックしますか?
構成を一度の実行でチェックします。翻訳の呼び出しは行わず、--live を指定しない限り API キーの値も読み込みません。--live を指定すると、プロバイダーの言語リストを取得するために、API キーを送信します。チェックの対象は、設定ファイル、フォーマット、プロバイダー、API キーの変数、ネットワークポリシー、ソースファイル、ロケールのサポートです。さらに、複数形、ロケールコード、残存しているロケールの状態、verbatra.limits.json についての情報レポートも出力します。チェックの完全な表は、verbatra doctor にあります。
AI エージェントに verbatra のセットアップや操作を任せられますか?
はい。4 つの方法があります。コーディングエージェント向けのセットアッププロンプト(AI エージェントで verbatra をセットアップする)、自分のループで使う --json 出力(JSON で verbatra をスクリプト化する)、開いた Studio タブの WebMCP ツール(ブラウザーエージェントで Studio を操作する)、stdio MCP サーバー(verbatra mcp)です。Studio と MCP サーバーでプロバイダーの費用が発生するのは、--allow-spend オプションを指定した場合だけです。--json を使うループでは、実際の translate がすぐに費用を発生させます。そのため、スクリプトやエージェントは、先に人の了承を得る必要があります。
このサイトは AI エージェントやクローラー向けに何か公開していますか?
はい。ビルド時に生成される 3 つの静的ファイルがあり、どのロケールで閲覧していても、常に英語です。
/llms.txt:すべてのドキュメントページのタイトルと説明を、サイドバーと同じグループ分けで並べた厳選インデックスです。Markdown のリンクで構成されています。/llms-full.txt:ドキュメント全体を 1 つのファイルにまとめたものです。各ページのレンダリング後の内容を順番に連結しており、リンクをたどらずに内容を直接取り込むエージェント向けです。/.well-known/ai.txt:AI クローラーに対する利用ポリシーです。このプロジェクトが MIT ライセンスであり、この内容のクロール、インデックス、引用を歓迎することを伝えます。
3 つとも、フッターの「エージェント向け」列からリンクされています。
このサイトのコンテンツは AI で翻訳されていますか?
大部分は AI で翻訳されており、2 つの異なる仕組みを使っています。UI の部分(ナビゲーションのラベル、ボタン、フッター、ランディングページの文章、ランディングページの FAQ)は messages/en.json と、ほかの言語ごとに 1 つずつある兄弟ファイルにあります。これらは機械翻訳です。英語のソースが変わった後に pnpm i18n を実行して、next-intl-json フォーマットを対象に Gemini プロバイダー経由で verbatra 自身が翻訳する場合と、リポジトリで作業する AI コーディングエージェントが翻訳し、その出力を verbatra import で取り込む場合があります。これは、このプロジェクトが自分のツールを自分で使っているということです。また、docs-i18n-check ワークフローは、ロケールファイルが英語のソースからドリフトした pull request を失敗させます。今読んでいるドキュメントの本文は、このページを含むすべてのガイドとリファレンスのページで、ロケールのサフィックス付きの MDX(page.mdx と、ほかの言語ごとに 1 つずつある page.<locale>.mdx)です。これも AI で翻訳されていますが、自動化された処理の流れの外にあります。pnpm i18n が翻訳するのは構造化されたロケールファイルのフォーマットだけで、Markdown には触れないため、これらのページを変更することはありません。代わりに、AI エージェントが、英語のソースを編集するのと同じ変更でドキュメントページを翻訳します。そのため、すべての言語が同時に反映されます。英語以外のすべてのページに機械翻訳の通知が表示されるのは、このためです。
この 2 つの手順で出てきたものが、すべてそのまま使われているわけではありません。法的ページの一部を含め、一部のテキストはロケールファイルに直接書かれたり、修正されたりしています。訳文はできる範囲で確認していますが、すべての訳文を人がレビューしているわけではありません。公開される前にレビューを経ていない訳文もあるため、誤りが含まれている場合があります。同じ過程は、プライバシーポリシーにも書かれています。
翻訳されたテキストに不自然な点があれば、どちらの場合も issue を作成してください。UI の文章は、英語のソースを修正して翻訳し直すか再インポートするか、または該当するロケールファイルを直接修正します。ドキュメントの本文は、MDX ファイルを直接編集して pull request を送ります。
GitHub で編集