リファレンス / CLI
機械翻訳されたページ
verbatra init
ロケールファイルから検出して、このプロジェクト用の verbatra 設定ファイルと .env の例を作成します。対話式でも、完全な無人実行でも使えます。
プロジェクトの設定を作成します。init は、verbatra.config.ts、プロバイダーの API キー変数の名前を記した .env.example(API キーの値は書きません)、.env、.env.local、.verbatra-local/、verbatra.cache.json の .gitignore エントリを書き込みます。i18next-json の場合、設定ファイルにはコメントアウトされた extract ブロックも付き、コメントを外して使えます。init は最初にプロジェクトにすでにあるロケールファイルを読むので、通常はプロバイダーを伝えるだけで済みます。
書式
verbatra init [flags]例
# prompt for anything not passed or detected
verbatra init --provider gemini
# fully unattended, one JSON document on stdout
verbatra init --provider gemini --yes --json
# choose the format and pattern yourself
verbatra init --provider deepl --format yaml --path "config/locales/{locale}.yml" --yes
# a local server that needs no key
verbatra init --provider openai-compatible --base-url http://localhost:11434/v1 --model llama3.1 --yes
# a self-hosted LibreTranslate server, no language model
verbatra init --provider libretranslate --base-url http://localhost:5000 --yes
# human-only: no provider, no API key
verbatra init --provider none --yes
# also set the project up for coding agents
verbatra init --provider gemini --yes --agent
# wire Cursor and VS Code, and only show what would change
verbatra init --agent --client cursor,vscode --dry-runオプション
| オプション | 引数 | デフォルト | 説明 |
|---|---|---|---|
--provider | <id> | なし(質問されない場合は必須) | 作成する対象のプロバイダー:anthropic、openai、gemini、deepl、google-translate、opencode、openai-compatible、libretranslate、none のいずれか |
--format | <id> | 検出された値、なければ i18next-json | ロケールファイルのフォーマット。フォーマットにある ID のいずれか |
--source | <locale> | 検出された値、なければ en | 文字列が書かれているソースロケール |
--targets | <locales> | 検出された値、なければ de | 翻訳先のターゲットロケールを、カンマ区切りで指定 |
--path | <pattern> | 検出された値、なければフォーマットの通常のレイアウト(検出) | ロケールファイルのパターン({locale} プレースホルダーが必須) |
--model | <name> | 作成時のデフォルト | モデル。openai-compatible では必須で、anthropic、openai、gemini、opencode では省略可能 |
--base-url | <url> | なし | サーバーの URL。openai-compatible と libretranslate のみで、どちらでも必須 |
--api-key-env-var | <name> | OPENAI_ | openai-compatible が API キーを読み込む変数 |
--yes | なし | オフ | 質問しない(渡されても検出されてもいない項目にはデフォルトを使用) |
--force | なし | オフ | 内容が異なる既存の verbatra.config.ts を上書きする |
--agent | なし | オフ | コーディングエージェント用のセクションを AGENTS.md または CLAUDE.md に、verbatra MCP サーバーを検出された各クライアントのプロジェクト設定にも書き込む(コーディングエージェントを設定する) |
--client | <ids> | 検出された値 | --agent が、検出されたクライアントの代わりに設定するクライアントをカンマ区切りで指定:claude、cursor、vscode、codex、gemini、all。--agent が必要 |
--dry-run | なし | オフ | init が書き込むまたは変更するすべてのファイルを報告し、何も書き込まない(ドライラン) |
グローバルオプションのうち --cwd と --json は使えますが、--config は使えません。ここでの --cwd は、スキャンして書き込むディレクトリで、すでに存在している必要があります。--json では質問されません。
動作
対話式の質問
オプションが常に優先されます。省略したものは、まずプロジェクトから検出されます。そのうえで、stdin がターミナルで --yes も --json も指定されていなければ質問され、それ以外の場合は --yes を指定したときに限り、デフォルトが使われます。Enter を押すと、提案された値が採用されます。--targets '' のように空の値を渡したオプションは使い方の誤り(INVALID_)で、デフォルトを求めるものとして扱われることはありません。質問の途中で stdin が終了すると(Ctrl-D)、init は終了コード 2 と MISSING_ で終了します。
各回答は入力のたびにチェックされます。無効な回答は stderr に理由が示され、再度質問されます。最大 3 回で、それまでの回答は保たれます。3 回目も無効な場合、init はその回答のエラーコード(INVALID_ など)で停止し、代わりに渡すべきオプションを示して、何も書き込みません。
検出
init は、フォーマットアダプターが引き受けるファイルをディレクトリからスキャンします。隠しディレクトリ、node_、ビルド出力は飛ばします。そして各パスのうち、de.json、messages_、de.lproj/、Android の values-de/ のようにロケールを表す部分を見つけます。最も多くのロケールをカバーするファイルパターンが採用され、次の項目が埋まります。
format:一致したすべてのファイルを読めるアダプターを持つ、唯一のフォーマット(JSON のアダプターはどれも.jsonを読むため、JSON ファイルではpackage.jsonで一致する依存パッケージ(i18next、vue-i18n、next-intl、@ngx-translate/core)が 1 つだけの場合にそれで決まる)files.patternとfiles.localeStyle:ファイルがpt_と綴られていればBR posix、values-*ディレクトリならandroid、それ以外はliteralsourceLocale:.xcstringsカタログのソース言語。なければen、または見つかった唯一のen-*ロケール。それもなければ、見つかった唯一のロケールtargetLocales:見つかった、ソース以外のすべてのロケール
ロケールファイルの隣に、ロケール名のない文字列を保持するファイルがある場合(messages.properties、Strings.resx、gettext の app.pot など)、unqualifiedSourceFile として報告されます。verbatra はそのようなファイルからソースを読み取れないため、init はソースロケールを推測しません。--yes を付けていても --source を渡します。次の手順には、ベースファイルをリネームまたはコピーする先のファイル名が示されます。
ロケールファイルがまったくない場合は、依存パッケージだけでフォーマットが決まります。パターンは、フォーマットごとの通常のレイアウトに従います。これは技術スタックを選ぶにフォーマットごとに載っているものです。
apple-xcstrings カタログは、すべてのロケールで共有される 1 つのファイルで、verbatra が作成することはありません。先に Xcode で作成してください。--format、--path、--source は、検出に上書きされるのではなく、検出の範囲を絞ります。そのため --format yaml は YAML ファイルだけを対象にします。
init は、同程度の候補から推測で選ぶことはありません。ファイルを読めるフォーマットが複数ある場合(i18n の依存パッケージがないプレーンな JSON)は、終了コード 2 と FORMAT_ で終了します。同点のファイルパターンが複数ある場合(名前空間ごとに 1 ファイル)は、終了コード 2 と LAYOUT_ で終了します。どちらも候補を一覧表示するので、--format または --path を渡して選びます。ターミナルでは、代わりに質問されます。
無人実行
ターミナルがない場合や --json を付けた場合、init は質問しません。渡されておらず、検出もされず、--yes のデフォルトもない値はエラーになります。init は終了コード 2 と MISSING_ で終了し、指定されていないすべてのオプションを示します。あいまいさや無効なオプションがある場合も、まだ指定されていないオプションが一覧表示されるので、1 回の実行で、エージェントが渡すべきものがすべてわかります。--provider にはデフォルトがなく、openai-compatible の --base-url と --model、libretranslate の --base-url にもありません。エージェントが実行するコマンドは次のとおりです。
npx @verbatra/cli init --provider gemini --yes --jsonJSON 出力
スキーマ:init-envelope.json がエンベロープ全体を検証します。ほかのスキーマはスキーマに一覧があります。
--json を付けると、stdout にはちょうど 1 つの JSON 出力のエンベロープ(envelope)が出力されます。その result の形は次のとおりです。
interface InitResult {
configPath: string; // absolute path of verbatra.config.ts, or of the config --agent kept
files: { path: string; action: "created" | "overwritten" | "updated" | "unchanged" }[];
dryRun: boolean; // true under --dry-run: files holds the planned actions
config: { // the config that was validated and written
sourceLocale: string;
targetLocales: string[];
format: string;
files: { pattern: string; localeStyle?: "posix" | "android" };
provider: { id: string; options?: Record<string, unknown> };
sensitiveData?: { mode: "warn" };
} | null;
sources: { // where each value came from
provider: "flag" | "prompt";
format: "flag" | "prompt" | "files" | "dependencies" | "default";
pattern: "flag" | "prompt" | "detected" | "default";
sourceLocale: "flag" | "prompt" | "detected" | "default";
targetLocales: "flag" | "prompt" | "detected" | "default";
} | null;
apiKeyEnvVar: string | null; // the variable to set; null for provider none
detection: {
format: { id: string; from: "input" | "files" | "dependencies" } | null;
layout: {
pattern: string;
localeStyle: "literal" | "posix" | "android";
locales: string[];
sourceLocale: string | null;
unqualifiedSourceFile: string | null;
files: string[];
} | null;
ambiguities: { subject: "format" | "layout"; candidates: string[] }[];
confidence: "high" | "medium" | "low" | "none";
reasons: string[]; // one sentence per decision or doubt
} | null;
agent: { // null without --agent
instructionsFile: "AGENTS.md" | "CLAUDE.md";
mcpServer: "added" | "present" | "differs" | "skipped" | null; // Claude Code; null when not wired
configKept: boolean; // true when --agent kept an existing config
clients: {
id: "claude" | "cursor" | "vscode" | "codex" | "gemini";
file: string; // the client's config file, such as .mcp.json
server: "added" | "present" | "differs" | "skipped";
reason: "plugin" | "symlink" | null; // why the client was skipped
selectedBy: "flag" | "markers" | "default";
markers: string[]; // the client's marker files found in the project
}[];
} | null;
nextSteps: { description: string; command: string | null }[];
}confidence は、ファイルだけですべてが決まった場合は high、規約や依存パッケージが空白を埋めた場合(en をソースとするなど)、または空白が残った場合は medium、ロケールファイルの裏付けがないフォーマットの場合は low、何も検出されなかった場合は none です。sources の default は、再確認すべき値です。nextSteps の末尾には、次に実行するコマンドそのものが入ります。
FORMAT_、LAYOUT_、INVALID_、INVALID_ のエラーエンベロープには、選択肢となる値の candidates も含まれます。答えのないオプションが残るすべての使い方の誤りには、それらを示す missing が含まれます。たとえば "--source <locale>" です。
プロバイダー
--provider noneは、optionsのない人手のみのモード(機械翻訳なしで実行するを参照)の設定ファイルを作成し、.env.exampleは書き込みません。API キーが読み込まれることがないためです。--provider openai-compatibleは、--base-urlと--modelからローカルまたはセルフホストのサーバー用の設定ファイルを作成し、maxOutputTokens: 4096を設定します。API キーは省略可能です。API キーが不要なサーバーでは、OPENAI_を未設定のままにします。COMPATIBLE_ API_ KEY --api-key-env-varは別の変数を指定するもので、LLM_のように大文字で書きます。拒否された値は、API キー自体だった場合に備えて、そのまま表示されることはありません。API_ KEY --provider libretranslateは、セルフホストの LibreTranslate サーバー用の設定ファイルを、--base-urlだけから作成します。たとえばhttp://localhost:5000です。--modelと--api-key-env-varは拒否します。.env.exampleには、--api-keysで起動したサーバー向けにLIBRETRANSLATE_が書かれます。API_ KEY
init は、変数の名前を設定ファイルと .env.example に書き込みますが、値は書きません。また、認証情報、クエリ文字列、フラグメントを含むベース URL(https://user:key@host、https://host/v1?api-key=...)は拒否します。API キーがコミットされる設定ファイルに入り込みかねないためです。
既存のファイル
同じ回答で init をもう一度実行しても、何も変わらず、成功します。内容が異なる verbatra.config.ts は、--force を渡さない限り CONFIG_ で拒否され、この拒否は質問やほかのエラーより先に起きます。ディレクトリにある別の verbatra 設定ファイル(.verbatrarc.json、または package.json の verbatra プロパティ)は、先に読み込まれてしまうため、--force を付けても拒否されます。init が拒否した場合、何も書き込まれません。親ディレクトリの設定ファイルがこのディレクトリを対象にしている場合は、stderr に警告が出ます(ドライランでも同様)。ここでは新しい verbatra.config.ts がそれを置き換えます。
init が書き込めないディレクトリは、ファイルと、すでに書き込まれたファイルを示して INIT_ で拒否されます。プロジェクトの外、または存在しない場所を指すシンボリックリンクになっている verbatra.config.ts、.env.example、.gitignore は、何も書き込まれる前に INIT_ で拒否されます。既存の .env.example は残されます。そこに API キー変数の名前がまだない場合は、その 1 行だけが追加され、--force の下では、init 自身が書いたヘッダー行が新しいプロバイダー用に書き直されます。.gitignore には、足りないエントリだけが追加されます。
ドライラン
--dry-run は、実際の実行のすべてのチェックと拒否を実行します。ただし、読み取り専用ディレクトリなどによる書き込みの失敗は除きます。各ファイルについて would create、would update、would overwrite、unchanged を出力し、何も書き込みません。
コーディングエージェントを設定する
--agent は、プロジェクトをコーディングエージェント向けにも準備します。API キーの値は書き込まず、プロジェクトの外へのリンクを通して書き込むことは決してありません。次のものが追加されます。
- 指示ファイル:
<!-- verbatra:start -->と<!-- verbatra:end -->のマーカーの間にある verbatra のセクションで、エージェントに verbatra を教えるのスニペットと一言一句同じです。書き込み先はAGENTS.mdで、指示ファイルがCLAUDE.mdだけの場合はCLAUDE.mdです。両方ある場合はAGENTS.mdが優先されます。すでにこのセクションがあるファイルでは、マーカーの間のテキストが現在の内容に置き換えられてupdatedと報告され、すでに一致していればunchangedと報告されます。 - 各クライアントの MCP 設定:MCP クライアントを接続するの
verbatraサーバーのエントリで、--allow-spendもVERBATRA_もないMCP_ ALLOW_ SPEND npx -y @verbatra/mcpです。そのため課金ツールは表示されません。@verbatra/cliはこれらのエントリをAGENT_としてエクスポートしています。CLIENT_ CONFIGS
| クライアント | --client | ファイル | 検出元 |
|---|---|---|---|
| Claude Code | claude | .mcp.json | CLAUDE.md、.claude/、.mcp.json |
| Cursor | cursor | .cursor/mcp.json | .cursor/、.cursorrules |
| VS Code | vscode | .vscode/mcp.json(servers の下) | .vscode/mcp.json |
| Codex | codex | .codex/config.toml([mcp_ として) | .codex/ |
| Gemini CLI | gemini | .gemini/settings.json | .gemini/、GEMINI.md |
init は、検出したすべてのクライアントを設定します。マーカーが見つからない場合は Claude Code だけです。AGENTS.md が決めるのは指示ファイルで、クライアントではありません。mcp.json のない .vscode フォルダーは設定されません。それを設定するコマンドが次の手順に示されます。Gemini CLI は GEMINI.md を読みます。設定ファイルまたは GEMINI.md が指示ファイルを読み込まない場合は、その方法が次の手順に示されます。検出されたクライアントのうち、設定ファイルのパスがシンボリックリンクを通るものは、理由 symlink と次の手順を付けてスキップされます。--client は検出を置き換えます。不明な ID、空のリスト、--agent なしの --client は、終了コード 2 と INVALID_ で終了し、候補が示されます。
マーカーの外には触れません。ファイルが 1 エントリ 1 行で記述されている場合、ほかのサーバーとキーのバイト列、インデント、改行コードはそのまま保たれます。そうでない場合は、同じ内容でファイルが書き直されます。Codex のテーブルは末尾に追加されます。既存の verbatra サーバーには触れません。ファイルは unchanged と報告され、クライアントの server は、エントリが作成内容と一致すれば present、一致しなければ differs になり、differs の場合は nextSteps にも注意書きが加わります。
.claude/settings.json または .claude/settings.local.json で verbatra の Claude Code プラグインが有効になっている場合、init は .mcp.json をスキップします。Claude Code は理由 plugin と次の手順を付けて skipped と報告され、既存のエントリが削除されることはありません。シンボリックリンクの先にある設定ファイルは無視されます。
設定ファイルがすでにある場合、init --agent はそれを残し、エージェント用のファイルだけを書き込んで、kept verbatra.config.ts と出力します。質問はせず、何も検出しません。JSON の結果では、設定ファイルは unchanged として一覧され、agent.configKept は true になり、config、sources、apiKeyEnvVar、detection は null になります。設定のオプションか --force を渡すと、--agent なしの場合と同じように、設定ファイルが実行に戻ります。
init は、何も書き込む前に、次の場合に AGENT_ で拒否します。クライアントのファイルが、プレーンな JSON ではない(コメントや末尾のカンマは書き直さない)、オブジェクトではない、キー名が重複している、または servers の値がオブジェクトではない場合。.codex/config.toml が mcp_ または verbatra サーバーを、インライン、ドット付きキー、テーブルの配列で設定している、そのテーブルまたはその中のキー名が重複している、または文字列、配列、ヘッダーが閉じられていない場合。--client が指定するクライアントの設定ファイルのパスにシンボリックリンクがある、または指示ファイルがプロジェクトの外にリンクしている場合。指示ファイルに、対のないマーカー、順序が逆のマーカー、重複したマーカーがある場合。メッセージにファイルの内容が引用されることはありません。
終了コード
| 終了コード | 意味 |
|---|---|
0 | ファイルを書き込んだ、またはすでに最新 |
2 | 使い方の誤り:MISSING_、INVALID_、INVALID_、INVALID_、INVALID_、INVALID_、FORMAT_、LAYOUT_、CONFIG_、INIT_、AGENT_、または回答が有効な設定ファイルにならない場合の CONFIG_ |
各コマンドがこれらのコードをどう使うかは、終了コードの仕様を参照してください。
関連項目
- AI エージェントで verbatra をセットアップするは、このコマンドを使うエージェント向けのプロンプトです。
- クイックスタートは、init から最初の実行までを順に説明します。
- 設定ファイルは、作成された設定ファイルが設定するすべての設定キーを説明しています。
- プロバイダーは、プロバイダーのオプションと API キー変数を扱います。