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

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

機械翻訳されたページ

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

ロックファイルと来歴

verbatra.lock.json と verbatra.provenance.json の記録内容、ドリフトの検出方法、同時実行の直列化、両方をコミットする理由を説明します。

verbatra.lock.json は、すべての実行が差分を取る基準となるベースラインです。これがあるため、実行は最新のものをスキップし、ドリフトしたものだけを翻訳し直せます。隣の verbatra.provenance.json には、各値を誰または何が書いたかが記録されます。

記録される内容

ターゲットロケールごとに、翻訳済みのキー 1 つにつき、現在の訳文の元になったソースエントリのハッシュが 1 つ記録されます。ほかに version フィールドがあります。訳文もシークレットも含まれません。ハッシュは、ソース値に加えて、説明、意味、複数形のフラグ、プレースホルダーを対象にします。そのため、説明を変更しただけでもキーは古くなります。Unicode は NFC に、改行は LF に正規化されます。そのため、ソースファイルを CRLF の改行で保存し直しても、何も変わりません。

ドリフトの検出方法

ターゲットにない空白でないソースキーは、欠落として扱われます。ターゲットにあるキーは、現在のソースハッシュと記録されたハッシュを比較します。違いがあればソースが変更されたことを意味し、キーは翻訳し直されます。一致すれば送信されないため、ソースを編集せずに 2 回目を実行しても費用はかかりません。処理の流れは実行の仕組みで説明しています。

保護されたキー

例外は、人が書いたか、インポートした値を持つ変更されたキーです。デフォルトでは保護され、翻訳し直されずに古いまま残ります。

既存プロジェクトへの導入

レビュー済みの訳文がすでに入っているロケールファイルは、翻訳し直されません。初回の実行ではロックファイルがないため、古くなるものはありません。ターゲットにあるキーは値が保たれ、ないキーだけが翻訳されます。そして実行は、プロバイダーの費用をかけずに、すべてのソースハッシュをベースラインとして記録します。

導入の判断はキーの有無だけで行い、値は見ません。これには 2 つの影響があります。

  • 空の値や未翻訳の値は、翻訳済みとして扱われます:キーを削除します(空にするだけでは足りません)。次回の実行で翻訳されます。
  • 古い訳文は、最新として記録されます:初回の実行の前に修正するか、削除します。

同じルールで手書きの複数形も保たれるため、導入時に generatePlurals を使っても安全です。これらの結果をすべてプレビューするには、verbatra diff または verbatra translate --dry-run を実行します。

更新の仕組み

  • 全体の実行(translate、watch、インポート)は、ロケールのエントリを実行の結果で置き換えます。
  • Studio からの再翻訳などの単一キーの操作は、そのキーのエントリだけをマージします。

どちらの場合も、今回の実行で保留されたキー(整合性チェックやプロバイダーの呼び出しの失敗、無効な ICU のソース)は以前のハッシュを保つため、次回の実行で再試行されます。孤立したキーにはエントリが作られず、キーは並べ替えられるため、差分が小さく保たれます。

書き込みロック

同じロケールに同時に 2 つの実行が触れると、どちらも古いベースラインと比較して、費用を二重に払うおそれがあります。そのため、すべての書き込みは、そのロケールに対するプロセス間の書き込みロックを .verbatra-local/ の下で保持します。2 番目の書き込み側は待機し、その後、最初の書き込み側の結果を含むベースラインと比較します。ロケールが異なれば、互いにブロックしません。

書き込みロックが保証すること:

  • タイムアウトしても費用はかかりません:--lock-timeout が制限するのは、プロバイダーを呼び出す前の待機時間だけです。そのため、あきらめたロケールは何も費用をかけず、何も書き込みません。書き込んだファイルの記録は、デフォルトの 10 分まで待ちます。
  • 放棄された書き込みロックは実行を妨げません:このマシンでプロセスがなくなった書き込みロックは、すぐに回収されます。30 秒間更新されなかった書き込みロック(保持側は 10 秒ごとに更新します)も、放棄されたものとして扱われます。
  • 中断すると書き込みロックが解放されます:translate や import の実行中の Ctrl-C または SIGTERM、watch を強制停止する 2 回目の中断では、プロセスが終了する前にすべての書き込みロックが解放されます。
  • 失った書き込みロックでは書き込みが止まります:各書き込みロックにはランダムな所有権トークンがあり、書き込みのたびに確認されます。別の実行がその書き込みロックを回収していた場合、書き込みは LOCK_CONTENDED で止まり、何も書き込まれません。

書き込みロックが対象としないこと:

  • 別のマシンの書き込みロック(共有ネットワークドライブ)、および 0.12.0 より前の verbatra が作った書き込みロックは、自動では回収されません。解除の手順はトラブルシューティングにあります。
  • 確認と書き込みの間の長い停止:所有権トークンの確認の直後に停止した実行(スリープしたマシンや停止したプロセス)は、再開時に 1 回だけ書き込める場合があります。
  • ホスト名が同じホスト:Linux 以外では、ホスト名が唯一のマシンの識別子です。そのため、同じホスト名の 2 つのコンテナーが .verbatra-local/ を共有すると、相手の有効な書き込みロックを放棄されたものと取り違えるおそれがあります。それぞれに別のホスト名か作業コピーを割り当ててください。

表記の異なるロケールコード

ロックファイル、キャッシュ、来歴ファイルは、設定のロケールコードをキーにして状態を保持します。pt_BR を pt-BR に変えるようにコードの表記を変えると、次の translate または watch の実行が古い状態を 1 回だけ引き継ぎ、LOCALE_STATE_CARRIED_OVER を報告します。名前の変更より前に行ったソースの変更は、引き続き翻訳し直され、キャッシュされた訳文も再利用されます。

状態の移動は、あいまいさがない場合にだけ行われます。つまり、pt-BR 自身の状態がなく、ファイルがアンダースコアを使ったその表記(または sr-Latn に対する sr@latin のような gettext 表記)のちょうど 1 つで状態を保持している場合です。表記は大文字と小文字を区別せずに比較します。pt-BR にすでにある状態は上書きされません。移動を書き込めない場合は、そのロケールは実行されず LOCALE_STATE_NOT_CARRIED_OVER で失敗します。そのため次回の実行で再試行されます。ほかのロケールは通常どおり実行されます。

それまでは、すべての読み取りが古い状態を pt-BR のものとして扱い、何も書き込みません。そのため、古くなったキーは、古くなったキーとして報告されます。単一キーの書き込み(編集、再翻訳、レビューの判断)と verbatra import は、同じ方法で先に状態を移動します。verbatra doctor の locale-state チェックは、残された状態を示します。

欠落または破損

ロックファイルがない場合はエラーではなく、初回の実行として扱われます。解析できない、構造が正しくない、大きすぎる、またはサポートされないバージョンのロックファイルは、上書きされずに LOCK_FILE_INVALID で実行が失敗します。そのため、ベースラインを失わずに復元できます。

来歴:各値を誰が書いたか

verbatra.provenance.json には、現在ロケールファイルにある各値をどの書き込み経路が生み出したか、そして誰かがレビューしたかが記録されます。CI に固定されたものなど、古い verbatra はこのファイルを無視します。

出どころ書いた主体
machinetranslate、watch、単一キーの再翻訳でのプロバイダーの回答(プロバイダーの id と、わかる場合はモデルを含む)
memory完全一致のキャッシュヒット。人手のみの実行(プロバイダー none)が埋めるすべての値を含む
fuzzyあいまい一致のキャッシュのヒット
humanSDK の editEntry による人の編集(Studio の編集ダイアログが行うもの)
agentactor: "agent" を指定した editEntry による AI エージェントの編集
importverbatra import で受け入れられた行
unknown記録のなかった値へのレビューの判断、またはこのリリースが知らない出どころ

さらに 2 つは、読み取り時に導き出されます。unrecorded は記録がない値で、アップグレード後はすべてのキーがこれに当たります。external は、翻訳者の pull request、古い verbatra、マージなど、verbatra の外で値が変更されたために、記録のハッシュと一致しなくなったものです。各読み取りが返すフィールドは SDK リファレンスにあります。

ファイルが保証すること:

  • 安定した差分:訳文もタイムスタンプも含まず、並べ替えた 1 行 1 レコードです。そのため、何も変更しない実行ではファイルが変わりません。マージの競合では、残すロケールファイルに合うほうを採用します。一致しないレコードは external として読まれ、値が翻訳し直されないよう保護されます。
  • 新しい値には新しいレコード:値を変更する書き込みは、そのレコードを新しい未レビューのものに置き換えます。値とソースを変更しない書き込みは、レコードを保ちます。
  • 黙って上書きしません:ファイルが破損していると、ロケールファイルが変更される前に、すべての書き込みが PROVENANCE_FILE_INVALID で止まります。レポートでは、代わりに来歴のフィールドが省かれます。より新しい verbatra のファイルには手を加えません。読み戻せないほど大きくなる場合は書き込まれません(PROVENANCE_FILE_TOO_LARGE)。

改ざん防止にはなっていません。レポートにするには、機械翻訳の証跡を記録するを参照してください。

レビューの判断

記録には、approved または rejected のレビューの判断を、任意の reviewer 名とともに持たせられます。これを書き込むのは、Studio の Review(レビュー)ページ(Studio でレビューする)、SDK のレビュー関数(レビューと再翻訳)、MCP のレビューツール(verbatra mcp)です。MCP のツールは人の判断を中継するため、その人の名前が必須です。判断は、レビュー担当者が見たその値そのものに対して適用されます。値が変更されていた場合、判断は拒否されます。

  • 承認:変更するのは来歴ファイルだけです。ソーステキストが変更されると、再び未レビューとして読まれます。
  • 却下:値とそのロックファイルのエントリが削除されるため、次の translate の実行か、人が新しい値を書くまで、キーは欠落として読まれます。記録には削除されたテキストのハッシュが残り、キャッシュのエントリは破棄されます。そのため、実行で同じテキストが戻されることはありません。XLIFF は 1 つの訳文だけを削除できないため、却下は REVIEW_REJECT_UNSUPPORTED で拒否されます。

レビューキューと --require-reviewed のゲートに入るのは、machine、memory、fuzzy、agent の値だけです。check と lock.state の byReviewState の件数は、記録された判断ごとにすべての値を対象にします。そのため、人が書いた値やインポートした値のうち、判断のないものは、キューには入らなくても、そこでは unreviewed として数えられます。byOrigin と合わせて読んでください。

判断はコミットされるこのファイルに保存されます。そのため、レビューキューと verbatra check --require-reviewed はどこでも同じ状態を参照し、reviewer の名前は公開されます。verbatra がこの名前を自動で入力することはありません。

両方のファイルをコミットする

verbatra.lock.json と verbatra.provenance.json をロケールファイルと一緒にコミットし、手で編集しないでください。この 2 つは、チームと CI が差分を取る基準であり、ロールバックが復元する対象です。

GitHub で編集

このページの内容