リファレンス / CLI
機械翻訳されたページ
終了コードと JSON 出力
終了コードの規約、--json を付けたコマンドが出力するエンベロープ、CLI 自身が報告するコード、stderr とターミナルへの出力の仕組みを説明します。
スクリプトや CI のステップが、コマンドをまたいで頼れる内容をまとめています。各コマンドのページには、そのコマンド固有の内容だけを載せています。
終了コード
CI のステップは、終了コードで分岐します。終了コードが規約です。
| 終了コード | 意味 |
|---|---|
0 | 成功(コマンドごとの内容は表の下に一覧) |
1 | 実行はできたが、結果がクリーンではない:translate または import が、失敗または一部完了のロケールを 1 つ以上残して終了した。check が同期していないロケールを検出した(--qa では整合性エラーのあるコミット済みの訳文、--qa に --strict を加えるとレビューの警告や不完全な複数形、--require-reviewed では誰も承認していない機械翻訳の訳文、--sensitive ではソースファイルや用語集で機密情報に見える内容も対象)。check --file がファイルの構文エラーまたは整合性エラーを検出した(--strict ではレビューの警告や不完全な複数形も対象)。diff が欠落または変更されたキーを検出した(--unused では、完全なスキャンで未使用のソースキーを検出した場合)。report provenance が、破損した verbatra.provenance.json またはより新しい verbatra が書いたものを検出した。doctor が失敗したチェックを 1 つ以上検出した。types --check がコミット済みの宣言が古いことを検出した。studio または mcp がサーバーの停止中に失敗した |
2 | 実行できなかった:実行全体のエラー(不正な設定、読み込めないソース、破損したロックファイル、プロバイダーが対応しないロケール)、使い方の誤り(空の --locales リスト、INVALID_、不正な --debounce や --port)、設定にない --locales の値(UNKNOWN_)、必要なオプションが足りない init、条件に合うフォーマットやファイルパターンが複数見つかった場合、既存の設定ファイルを上書きしない場合、有効な設定ファイルを作成できない場合、watch の起動または停止の失敗、studio が設定を読み込めない、@verbatra/studio をインポートできない、またはサーバーを起動できない場合、mcp に存在しない --config のパスが渡された、@verbatra/mcp をインポートできない、サーバーを起動できない、またはインストール済みの @verbatra/mcp で --redact-values に対応できない場合(探索で設定ファイルが見つからない、または無効な場合は、未設定の状態で起動します) |
3 | 人手のみのプロジェクト(provider: { id: "none" })で translate(ドライランと --estimate を含む)が正常に終了したが、人手翻訳が必要なキーが残った。失敗または一部完了のロケールがある場合は、引き続き 1 で終了する |
130 | 書き込みロックを解放した後に、translate または import が Ctrl-C(SIGINT)で中断された。または watch、studio、mcp が 2 回目の中断で強制停止された |
143 | 書き込みロックを解放した後に、translate または import が SIGTERM で停止された |
終了コード 0 の意味は、コマンドごとに次のとおりです。
translateまたはimport:すべてのロケールが完了したcheck:すべてのロケールが同期しているdiff:未処理の変更がないreport:レポートを出力したdoctor:構成に問題がないextract:スキャンが完了したpseudo:疑似ロケールを生成したtypes:宣言を生成したexport:ブックを書き込んだtmx:翻訳メモリをインポートまたはエクスポートしたinit:プロジェクトの設定を作成した、またはすでに最新であることを確認したwatch、studio、mcp:正常に停止した--helpまたは--version:ヘルプまたはバージョンを出力した
130 と 143 では、stderr の最後に verbatra: interrupted (SIGINT), released locks(または SIGTERM)が出力されます。--json ではレコード {"type":"interrupted","signal":"SIGINT","locksReleased":true} が出力されます。書き込みロックの解放に失敗した場合や 5 秒以内に終わらなかった場合は、その旨を示す行が出力されます(could not release locks: <reason> または lock release did not finish within 5s。どちらも、残った書き込みロックの見つけ方と削除方法が続きます)。JSON のレコードには "locksReleased":false が入り、"reason":"failed"(message も付く)または "reason":"timed-out"(deadlineMs も付く)が続きます。
知っておくとよい特殊なケースがあります。
- 一部完了(partial)のロケールは失敗として数えられます。ファイルは書き込まれたものの、一部のキーがまだ欠落している状態です。多くはプロバイダーのサブバッチが失敗したか、整合性ゲートが訳文を拒否したことが原因です。失敗したロケールとまったく同じように
1で終了します。2 つを区別するには、サマリーのpartialを読みます。値が 1 つも書き込まれなかったロケールは、一部完了ではなくfailedになります。そのため、一部完了の後に同じimportを再実行すると、失敗として読まれます。前回書き込んだ分はすでに変更がなく、拒否された行だけが残っているためです。失敗したサブバッチは、プロバイダーのエラーコードを示すSUB_の通知をロケールに残します。失敗が構造化されたプロバイダーのエラーではなかった場合はBATCH_ FAILED PROVIDER_です。CALL_ FAILED - プロバイダーが対応しないロケールも、実行全体のエラーです。失敗した 1 つのロケールとして扱われることはありません。
translate(ドライランと--estimateを含む)、起動時のwatch、単一キーの再翻訳は、プロバイダーを生成する前、また費用が発生する前に、LOCALE_で拒否して終了コードUNSUPPORTED_ BY_ PROVIDER 2で終了します。判断の基準は、DeepL と Google Cloud Translation 用に verbatra が同梱している言語テーブルです。LLM プロバイダーはどのロケールも受け付けます。ほかのロケールを翻訳するには、--localesでそのロケールを外します。理由はverbatra doctor --localesで確認できます。詳しくは実行前の対応確認を参照してください。 - 破損したロックファイルは、
translateでもimportでも実行全体のエラーです。失敗した 1 つのロケールとして扱われることはありません。ロックファイルは共有される 1 つのファイルです。実行中にロックファイルが破損した場合、残りのロケールを続行せず、2で実行を止めます。中断前に書き込まれたものはディスクに残ります。ロックファイルを修正して、コマンドを再実行してください。 - 1 回の中断は正常な停止です。長時間動作する 3 つのコマンド(
watch、studio、mcp)は、いずれも0で終了します。ただし、それ以外では同じ動作とは限りません。停止自体に失敗した場合、watchは2で終了し、studioとmcpは1で終了します。 watch中に実行が失敗した場合は、出力ストリームのレコードとして現れます。ゼロ以外の終了コードにはなりません。exportにはロケール単位の失敗モードがありません。0または2で終了し、1にはなりません。doctorは、壊れた設定を、ほかのどのコマンドとも違う扱いで読み取ります。探索で見つからない設定や、検証に失敗する設定は、失敗したチェックとなり終了コード1です。それを報告するのがこのコマンドの役割だからです。2で終了するのは、存在しない--configのパスを明示した場合など、まったく実行できないときだけです。- 規約の外にある失敗モードが 1 つあります。使い方の誤りではない解析の失敗は、再スローされます。バイナリはそれをキャッチしないため、6 つのコードのいずれでもなく、処理されない reject に対する Node のデフォルトの処理が適用されます。
- 保護されたキー(人が書いた、インポートした、または verbatra の外で変更された古い値、あるいは固定されたキー)は、プロバイダーがあるプロジェクトの
translateの終了コードを変えません。0で終了し、残したキーの件数を stderr に出力します(固定されたキーは数えません)。checkは、人が解決するまでそのキーが古いままなので、引き続き1で終了します。人手のみのプロジェクトでは、終了コード3の対象として数えられます。
JSON 出力
studio と mcp を除くすべてのコマンドが、--json で stdout に機械可読の出力を返します。対象は translate、watch、check、diff、report、export、import、tmx、doctor、pseudo、types、extract、init です。すべてのレコードは 1 行で、同じエンベロープ(envelope)で包まれています。そのため、1 つのフィールドで分岐でき、どのコマンドのペイロードを持っているかを推測する必要はありません。
type Envelope<TResult> =
| { ok: true; version: 1; command: string; result: TResult }
| {
ok: false;
version: 1;
command: string | null;
code: string;
message: string;
causeCode?: string; // the code of the error this one wraps, when it has one
candidates?: string[]; // the values to choose from, on an error that has them
missing?: string[]; // the flags still to pass, on an init usage error
hint?: string; // the next step that resolves the error, when there is one
};version は、パッケージのバージョンではなく、このエンベロープの形のバージョンです。整数なので、範囲を解析せず === で比較できます。既存のフィールドの意味が変わるか、フィールドがなくなる場合にだけ変わります。新しいフィールドは、バージョンを上げずに追加されることがあります。知らないフィールドは無視してください。
実行全体が失敗した場合は、ok: false のレコードをちょうど 1 つ stdout に書き込み、2 で終了します。その code は stderr の行に出る安定したエラーコードと同じです。分岐にはこれを使います。
{ "ok": false, "version": 1, "command": "translate", "code": "CONFIG_INVALID", "message": "..." }command が null になるのは、サブコマンドが決まる前に失敗した場合だけです。candidates は、init の FORMAT_ のように選択を求めるエラーにだけ現れ、選べる値を一覧します。missing は、オプションが未指定のままの init の使い方の誤りに現れ、まだ渡すべきオプションを 1 つずつ示します。causeCode は、別のコード付きエラーを包んでいる場合に現れます。たとえば MISSING_ が原因の PROVIDER_ です。このとき stderr の行は (cause: MISSING_ で終わります。
hint は、エラーに次の手順がある場合に現れます。エラーを解決する短い命令文が 1 つ入ります。たとえば、API キーがない場合は "Set GEMINI_、USAGE_ の場合は "Run `verbatra check --help` to see the options and arguments it accepts." です。message を解析する代わりに、これに従ってください。変数、オプション、パスは示しますが、API キーの値は示しません。SDK、プロバイダー、フォーマットアダプターのすべてのコードにヒントがあります(SDK は同じテキストを errorHint として公開しています)。CLI_ を除くすべての CLI のエラーコードにもあります。--json を付けない場合は、--quiet を指定していなければ、同じテキストがエラー行の後に next: ... として stderr に出力されます。mcp --json は例外で、stderr に USAGE_ の 1 行を出して拒否され、エンベロープも next: も出力されません。studio と mcp の起動時のエラーにも next: 行は付きません。
成功したエンベロープの result はコマンドごとに異なり、各ページの JSON 出力で説明しています。extract、translate、watch、check、diff、report、doctor、pseudo、types、export、import、tmx、init です。
スキーマ
--json が出力するすべてのレコードには、JSON Schema(draft 2020-12)があります。スキーマは npm パッケージに同梱され、固定の URL で提供されています。スクリプト、エージェント、エディターは、説明文を読まなくても出力を検証できます。出力のスキーマはすべて、上記のエンベロープの規約が約束するとおり、一覧にないプロパティを許可します。コピーして使う場合も、そのままにしてください。設定ファイルのスキーマは意図的な例外です。書く内容を記述するものなので、タイプミスを見つけられるよう、不明なキーを拒否します。
| ドキュメント | URL | パッケージ内のファイル |
|---|---|---|
| 成功またはエラーを問わないエンベロープ | envelope.json | @verbatra/cli/schemas/envelope.json |
1 つのコマンドのエンベロープ(result を含む) | https://verbatra.kreitz-webdev.de/schema/v1/<command>-envelope.json | @verbatra/cli/schemas/<command>-envelope.json |
| エラーのエンベロープ | error-envelope.json | @verbatra/cli/schemas/error-envelope.json |
エンベロープを除いた init の結果だけ | init-result.json | @verbatra/cli/schemas/init-result.json |
| stderr の JSON 行:進捗、書き込みロックの待機、中断 | stderr-record.json | @verbatra/cli/schemas/stderr-record.json |
| 設定ファイル | config.json | @verbatra/sdk/schemas/config.json、または @verbatra/sdk/config-schema.json($id と title がない同じスキーマ) |
各コマンドのページでは、JSON 出力の項目からそのエンベロープにリンクしています。https://verbatra.kreitz-webdev.de/schema/v1 には、すべてのドキュメントがタイトルとともに一覧されています。コマンドのエンベロープは、$ref の URL で result のスキーマを指しています。バリデーターはそれをネットワーク経由で読み込みます。先にそれらのファイルを登録しておけば、node_ から読み込みます。
v1 はエンベロープの version: 1 に対応し、常に最新のリリースを提供します。フィールドの追加は v1 のままです。ペイロードを壊す変更では、エンベロープの version を上げて /schema/v2/ を追加します。設定ファイルのスキーマも同じ URL の仕組みを使いますが、設定ファイル自体の変更に従います。URL は常に最新のリリースを提供しますが、npm から取得したコピーはそのバージョンのままです。そのため、スキーマが閉じた値を列挙している箇所(stderr レコードの type やエンベロープの command など)では、古いコピーが新しい CLI のレコードを拒否することがあります。
CLI のエラーコード
CLI 自身がこれらのコードを報告します。同じ一覧は、@verbatra/cli から CLI_(型は CliErrorCode)として公開されます。スクリプトでコードを照合できます。これ以外のコードは、SDK、プロバイダー、フォーマットアダプターのいずれかに由来します。各コードの意味、報告するコマンド、次の手順はエラーコードにあります。
stderr のエラー
すべてのエラーは、どちらのモードでも、構造化された 1 行(verbatra: error [CODE] message)として stderr に出力されます。0.12.0 以上では、引数の解析エラー(未知のオプションやコマンド、引数の不足)も含まれます。verbatra: error [USAGE_ を出力して 2 で終了します。以前は、コードのない commander 自身の error: unknown option '--nope' が出力されていました。init も 0.12.0 以上では同じ書式に従います。以前は、プロバイダーが指定されていない場合に、コードのない verbatra: --provider is required (...) が出力されていました。0.12.0 以上では、--json を付けない場合はヒントが next: ... として行の後に続きます。--json を付けた場合は、解析エラーが hint 付きの USAGE_ エンベロープを stdout に書き込みます。mcp は stdout をプロトコルのために使うため、--json は stderr だけで拒否します。studio と mcp の起動は、構造化された行の例外です。@verbatra/studio または @verbatra/mcp がインストールされていない場合、stderr にはインストール手順だけが出力され、verbatra: のプレフィックスは付きません。--json を付けた場合、解析エラーの message は、error: のプレフィックスを含む commander 自身のテキストです。--json を付けない場合も、失敗した実行が stdout に何かを書き込むことはありません。進捗と書き込みロックの待機のレコードは常に stderr に出力されます。そのため、stdout にはエンベロープだけが出力されます。
ターミナル出力
結果は stdout に出力されます。進捗、通知、ヒント、警告、エラーは stderr に出力されます。verbatra は、stderr の出力先に合わせて表示を切り替えます。
- 対話型のターミナルでは、
error、[ok]、next:などの固定ラベルに色が付きます。300 ms を超えるステップでは、ASCII のスピナー(spinner、| / - \)が表示されます。 - stderr がパイプで渡されているか、リダイレクトされている場合、
CIが空、0、false以外に設定されている場合、またはTERMがdumbの場合は、色もアニメーションもない、追記だけのプレーンな行になります。 - stdout に出力される
doctorレポートのステータスラベル([ok ]、[warn]、[fail]、[skip])は、stdout 自体が対話型のターミナルである場合に色が付きます。そのため、リダイレクトされたレポートは、FORCE_で色を有効にしない限りプレーンのままです。COLOR --jsonは色もアニメーションも追加せず、stdout にはエンベロープだけが出力されます。プレーンなverbatra:の警告行は stderr に出力される場合があります。そのため、受け取る側は{で始まる stderr の行だけを解析します。詳しくは JSON 出力を参照してください。
| オプションまたは変数 | 説明 |
|---|---|
-q、--quiet | 結果、警告、エラーだけを出力します。進捗行、next: のヒント、情報の stderr 行は出力されません。通知を含む結果のサマリーは残ります。コマンド名の前でも後でも指定できます |
--no-color | 出力に色を付けません |
NO_、NODE_、VERBATRA_ | 空でない値を設定すると色が無効になります。VERBATRA_ は FORCE_ よりも優先されます |
FORCE_ | 1、2、3、true、または空の値で、stderr や stdout がターミナルでなくても色を有効にします。それ以外の値(0 を含む)は無効にします。設定すると、NO_、NODE_、CI、TERM=dumb よりも優先されます。--no-color と VERBATRA_ は引き続き優先されます |
VERBATRA_ | 空でない値を設定すると、スピナーが静的な label... done (1.2s) の行に置き換わります。スクリーンリーダーやターミナルの録画向けです |
コマンドのページにある output のサンプルは、プレーンな形式です。対話型のターミナルでは、実行中のステップがスピナーの行として表示され、[ok] と経過時間で終わります。
ステータスを示す語は ASCII のプレーンな文字([ok]、[warn]、[fail]、[skip])です。そのため、どのターミナルやログでも同じように読めます。すべての行は、ほかの出力と同じ API キーの秘匿化を通ります。色が付くのは固定ラベルだけで、API キー、パス、メッセージに色が付くことはありません。