本文へスキップ
本文へスキップ

ドキュメント / コンセプト

機械翻訳されたページ

このページは自動翻訳のため、誤りや不自然な表現が含まれている可能性があります。正式な内容は英語版です。英語の原文を読む。

実行の仕組み

ソースロケールの読み込みと変更されたキーの検出から、訳文の書き込みとロックファイルの更新まで、翻訳処理の流れ全体を説明します。

実行は一連の処理です。ソースロケールを読み込み、各ターゲットをロックファイルと比較し、作業が必要な分だけをプロバイダーに送り、返ってきた内容をチェックして書き込み、結果を記録します。この流れは、CLI、SDK、watch のどれから実行しても同じです。

verbatra translate
en.json
de.json
"cart.checkout": "Checkout"
"cart.checkout": ""
"cart.empty": "Empty"
"cart.empty": "Leer"
"cart.total": "Total"
"cart.total": "Gesamt"
変更されたキーだけをプロバイダーに送ります。最新のキーには手を加えません。

ソースロケールを読み込む

フォーマットアダプターがソースファイルを、キーを持つエントリの中立的な集合として読み込みます。そのため、以降のどの処理もフォーマットを問わず同じように動きます。ソースキーの値がフォーマットのメッセージ構文として無効な場合(無効な ICU)、その値は壊れた状態でプロバイダーに送られず、除外して報告されます。ソースファイルが存在しない場合や解析できない場合は、実行が失敗します。詳しくは SOURCE_UNREADABLE と SOURCE_INVALID を参照してください。

ロックファイルのベースラインと比較する

実行が差分のみで済むのは、この比較があるためです。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)は差分の後で止まり、同じ形のサマリーを返します。プロバイダーを生成せず、ファイルも書き込みません。

一方、この設計は訳文の良し悪しを判断しません。その判断はレビューフラグと人が担います。

関連項目

GitHub で編集

このページの内容