ドキュメント / コンセプト
機械翻訳されたページ
実行の仕組み
ソースロケールの読み込みと変更されたキーの検出から、訳文の書き込みとロックファイルの更新まで、翻訳処理の流れ全体を説明します。
実行は一連の処理です。ソースロケールを読み込み、各ターゲットをロックファイルと比較し、作業が必要な分だけをプロバイダーに送り、返ってきた内容をチェックして書き込み、結果を記録します。この流れは、CLI、SDK、watch のどれから実行しても同じです。
ソースロケールを読み込む
フォーマットアダプターがソースファイルを、キーを持つエントリの中立的な集合として読み込みます。そのため、以降のどの処理もフォーマットを問わず同じように動きます。ソースキーの値がフォーマットのメッセージ構文として無効な場合(無効な ICU)、その値は壊れた状態でプロバイダーに送られず、除外して報告されます。ソースファイルが存在しない場合や解析できない場合は、実行が失敗します。詳しくは SOURCE_ と SOURCE_ を参照してください。
ロックファイルのベースラインと比較する
実行が差分のみで済むのは、この比較があるためです。verbatra は既存のターゲットファイルを読み込み(ファイルがなければ空として扱いますが、xliff と apple-xcstrings のライターはターゲットがないと拒否します)、各ソースキーをロックファイル(ロックファイルと来歴を参照)と比較します。ロックファイルは、以前に翻訳した内容の記録です。
| 分類 | 意味 | 実行の動作 |
|---|---|---|
| missing | ターゲットにキーがない | 翻訳する |
| changed | ソースが記録されたハッシュと一致しなくなった | 翻訳する |
| unchanged | ソースが記録されたハッシュと一致している、または記録がない | そのままにする |
| empty source | ソースの値が空白 | スキップして別に数える |
| orphaned | キーがターゲットにあり、ソースにない | 報告する。削除は --prune または prune: true のときだけ |
据え置かれたキー
翻訳の対象になるキーのうち、2 種類は据え置かれます。現在の値を人が書いた、またはインポートした変更済みキーは、デフォルトで保護されます(humanEdits)。pinnedKeys に一致するキーは、一切機械翻訳されません。どちらも、人が対応するまで古いままです。詳しくは人手翻訳を保護するを参照してください。
プロバイダーにバッチで送る
すべての候補訳は、まず翻訳キャッシュで検索されます。ヒットした値は再利用され、プロバイダーには届きません。キャッシュミスしたキーのうち、ソースの内容が同じものはまとめられます。そのため、同じテキストはキーごとではなく、ロケールごとに 1 回のリクエストで済みます。
グループは、最大 maxBatchSize 件(デフォルトは 50)のサブバッチに分けて、順番にプロバイダーへ送られます。各サブバッチには、エントリ、そのロケールの用語集の用語、tone が含まれます。サブバッチが失敗した場合(レート制限、タイムアウト、取り消された API キー)、そのキーは今回の実行では保留され、残りのサブバッチは処理を続けます。各プロバイダーがこれらの入力をどう使うかは、プロバイダーで説明しています。
レスポンスを検証する
プロバイダーの出力はデータであり、自由なテキストではありません。LLM プロバイダーの場合、レスポンスは固定のスキーマに一致する必要があります。
- 形式が不正なレスポンス、またはリクエストしていないキーを含むレスポンスでは、サブバッチ全体が失敗します。
- リクエストしたキーが欠けている、または重複している場合は、もう一度リクエストされます。
- その後も解決しないキーは、今回の実行では翻訳されません。
機械翻訳プロバイダーにはレスポンススキーマがありませんが、結果は同じ整合性ゲートを通ります。
整合性ゲートを実行する
スキーマに合っている訳文でも、壊れていることがあります。そのため verbatra は、プロバイダー自身の報告を信用せず、候補訳そのものから受け入れるかどうかを判断します。プレースホルダーが失われた候補訳、ICU メッセージやマークアップが壊れた候補訳、空で返ってきた候補訳、崩れた出力になった候補訳は、書き込まれずに保留されます。チェックの内容は翻訳の安全性にあります。
アダプター経由で書き込む
受け入れられた訳文はターゲットにマージされ、フォーマットアダプターがアトミックに、安定したキーの順序で書き込みます。ターゲットにすでにあるキーは位置を保ち、新しいキーは既存のキーの後ろにソースの順序で追加されます。中断された書き込みで、書きかけのファイルが残ることはありません。pull request をレビューする人が見る差分は、小さく安定しています。
ロックファイルを更新する
ロケールの書き込みが終わると、そのロックファイルのエントリが現在のソースのハッシュで更新されます。今回の実行で保留されたキーは以前のハッシュを保つため、次回の実行でも作業が必要なキーとして扱われます。各ロケールはプロセス間の書き込みロックの下で書き込まれます。そのため、重なった 2 つの実行が古いベースラインと比較したり、同じ呼び出しに 2 回費用を払ったりすることはありません。
ロケールは 1 つずつ、失敗はデータとして
各ターゲットロケールは個別に実行され、1 つのロケールが失敗してもほかのロケールは止まりません。実行はロケールごとのサマリーを返します。サマリーには、翻訳済み、未変更、孤立、保留、レビューのフラグ付き、通知が含まれます。各フィールドの内容は RunSummary にあります。
この設計が保証するのは次の点です。
- ソースを編集しない 2 回目の実行では、プロバイダーを一切呼び出しません。
- チェックが拒否した値は書き込まれず、保留された値が完了として記録されることもありません。
- ドライラン(
--dry-run)は差分の後で止まり、同じ形のサマリーを返します。プロバイダーを生成せず、ファイルも書き込みません。
一方、この設計は訳文の良し悪しを判断しません。その判断はレビューフラグと人が担います。
関連項目
verbatra translate:実行のオプション、出力、終了コード- ロックファイルと来歴:ベースラインが記録する内容
- 翻訳キャッシュ:再利用のキーの決め方
- 翻訳の安全性:整合性ゲートとレビューフラグ
- エラーコード:実行が報告しうるすべてのコード