リファレンス / CLI
機械翻訳されたページ
verbatra export
未翻訳の文字列を翻訳者への受け渡しファイルに書き出します。フォーマットは、スタイル付きの Excel ブック、ロケールごとの CSV か TSV、CAT ツール向けの XLIFF です。
翻訳が必要な文字列を、人が記入して verbatra import に戻せる受け渡しファイルに書き出します。デフォルトで含まれるのは、欠落した文字列と変更された文字列だけです。自動実行がプロバイダーに送るのと同じキーです。ソース値が空、または空白だけのキーには、ソーステキストを書くまで行が作られません。export はプロバイダーを呼び出さず、API キーも不要です。
書式
verbatra export [flags]例
# write the workbook with missing and changed strings
verbatra export
# only the German and French sheets, to a specific path
verbatra export --locales de,fr --out handoff/round-2.xlsx
# one de.csv and fr.csv under handoff/
verbatra export --format csv --out handoff
# one de.xlf and fr.xlf in XLIFF 2.0 for a CAT tool
verbatra export --format xliff2 --out handoffオプション
| オプション | 引数 | デフォルト | 説明 |
|---|---|---|---|
--out | <path> | verbatra-translations.xlsx(ほかのフォーマットでは verbatra-translations) | 受け渡しファイルの書き込み先。xlsx ではファイル、csv、tsv、xliff2、xliff12 ではディレクトリ |
--format | <format> | xlsx | xlsx(Excel ブック)、csv または tsv(ロケールごとに 1 ファイル)、xliff2 または xliff12(ロケールごとに 1 つの XLIFF ファイル) |
--locales | <list> | 設定されているすべてのターゲットロケール | カンマ区切りの一部だけをエクスポートします。設定にないロケールは UNKNOWN_、空のリストは INVALID_ で失敗し、どちらも終了コード 2 です |
--include-unchanged | なし | オフ | すでに最新の文字列もエクスポートします |
グローバルオプションの --cwd、--config、--json も使えます。
動作
CSV と TSV
--format csv と --format tsv は、エクスポートするロケールごとに <locale>.csv または <locale>.tsv を 1 つ書き込みます。列はブックのシートと同じ順序で同じ内容です。--out にはディレクトリを指定します。ディレクトリがない場合は作成されます。
区切り文字ファイルは差分を取りやすく、どこでも開けます。ただしセルの保護はなく、すべての列が編集可能で、Source hash 列も表示されます。編集されたハッシュは信頼されません。インポートでは、ハッシュを現在のソースと比較し、その行を保留します。
区切り文字ファイルのエクスポートでは、書き込んだロケールを記した非表示のマニフェスト .verbatra-export-csv.json または .verbatra-export-tsv.json も書き込まれます。--locales を絞ってあとからエクスポートすると、外れたロケールは廃止扱いになります。ファイルはディスクに残りますが、verbatra import は残存ファイルとして拒否します。エクスポートが出力ディレクトリから何かを削除することはありません。
XLIFF
--format xliff2 は XLIFF 2.0 を、--format xliff12 は XLIFF 1.2 を書き込みます。--out のディレクトリに、エクスポートするロケールごとの <locale>.xlf と、CSV のものと同じ仕組みの .verbatra-export-xliff.json マニフェストができます。各キーは、キー名を名前とする翻訳単位になります。プレースホルダーとマークアップは保護されたインラインコードになり、キーの説明と意味は注記になります。セグメントの状態は、ロックファイルとレビューの状態に従います(欠落または古くなったキーは initial、最新の場合は translated、承認済みの場合は reviewed)。詳しくは翻訳会社に受け渡す(XLIFF)を参照してください。
各ターゲットには、出どころも記録されます。XLIFF 1.2 では、プロバイダー、翻訳メモリ、AI エージェントのいずれかが書き、人が承認していないターゲットに state-qualifier="mt-suggestion" が付きます。XLIFF 2.0 では、翻訳単位の verbatra メタデータグループに origin と review-state が入ります。インポートはどちらも無視します。verbatra.provenance.json を読み込めない場合は、マーカーは書き込まれず、--json の結果に provenanceMarkers: "unavailable" が入ります。詳しくは機械翻訳の証跡を記録するを参照してください。
受け渡しファイルの書き込み先
受け渡しファイルは、プロジェクトルートの中にだけ書き込まれます。何かを読み込む前に、export は次のような --out を EXPORT_ で拒否します。プロジェクトルートの外に出るもの、またはプロジェクトが依存するファイルを指すもの(それ自体、または書き込むファイルを通して)です。依存するファイルとは、設定済みのロケールファイル、ロックファイル、来歴ファイル、翻訳メモリのキャッシュ、verbatra が探す設定ファイル、実行が読み込んだ設定ファイル、設定済みの glossary ファイルです。xlsx では、ファイルを指さないパス(out/ など)やプロジェクトルートそのものも拒否されます。名前は大文字と小文字を区別せずに比較され、チェックはシンボリックリンクを解決した後にもう一度行われます。
チェックを通ったパスでも、書き込み中に失敗することがあります(書き込み不可、パスがすでに使われている、ディスクが満杯など)。その場合、実行はファイルとファイルシステムのコードを示して EXPORT_ で止まります。
シートまたはファイルに名前を付けられないターゲットロケールがあると、エクスポートは WORKBOOK_ で止まります。xlsx のシート名は 1〜31 文字で、: \ / ? * [ ] のいずれも含められず、Instructions や、ほかのターゲットロケールのシート名と、大文字と小文字を区別せずに一致してはいけません。csv、tsv、xlf のファイル名は、空、.、.. にはできず、パス区切り文字、制御文字、: * ? " < > | のいずれも含められません。ブックをシリアライズできなかった場合にも、同じコードが使われます。
ターミナルへの表示
export は書き込み中に 1 行を表示します。受け渡すものがあった場合は、記入済みのファイルを取り込むインポートのコマンドも示します。
verbatra: exporting to xlsx... done (0.3s)
next: verbatra import verbatra-translations.xlsx (once your translators have filled it in)未処理のものがなく、--include-unchanged も指定されていない場合、ファイルには行がありません。このとき next: 行は、代わりに --include-unchanged を付けた同じエクスポートを示します。--format、--out、--locales、--cwd、--config は引き継がれます。
これらの行は stderr に出力され、--quiet で非表示になります。詳しくはターミナル出力を参照してください。
使用できない verbatra.limits.json は、stderr の警告とともに無視されます(--json では LIMITS_)。
JSON 出力
スキーマ:export-envelope.json がエンベロープ(envelope)全体を検証します。ほかのスキーマはスキーマに一覧があります。
--json を付けると、エンベロープに、受け渡しファイルの書き込み先とロケールごとの行数が入ります。
{
path: string; // absolute path: the workbook for xlsx, the output directory otherwise
locales: { locale: string; rows: number }[];
provenanceMarkers?: "written" | "unavailable"; // XLIFF formats only
limitsNotice?: { code: "LIMITS_FILE_IGNORED"; message: string };
}終了コード
| 終了コード | 意味 |
|---|---|
0 | 受け渡しファイルを書き込んだ |
2 | 実行できなかった:実行全体のエラー、拒否された出力パス(EXPORT_)、書き込めなかった受け渡しファイル(EXPORT_、WORKBOOK_)、または使い方の誤り |
export にはロケール単位の失敗モードがないため、1 で終了することはありません。すべてのコマンドが従う規約は終了コードを参照してください。
関連項目
- Excel や CSV で受け渡す:ブックのレイアウト、レビュー列、往復の流れ全体
- 翻訳会社に受け渡す(XLIFF):CAT ツール(翻訳支援ツール)向けの XLIFF の受け渡し
verbatra import:記入済みの受け渡しファイルの読み戻し