---
title: "ロックファイルと来歴"
description: "verbatra.lock.json と verbatra.provenance.json の記録内容、ドリフトの検出方法、同時実行の直列化、両方をコミットする理由を説明します。"
type: "concept"
---
# ロックファイルと来歴

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

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

## 記録される内容 [#記録される内容]

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

## ドリフトの検出方法 [#ドリフトの検出方法]

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

### 保護されたキー [#保護されたキー]

<AvailableFrom version="0.12.0" />

例外は、人が書いたか、インポートした値を持つ変更されたキーです。デフォルトでは[保護](https://verbatra.kreitz-webdev.de/ja/docs/protecting-human-translations.md)され、翻訳し直されずに古いまま残ります。

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

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

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

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

同じルールで手書きの複数形も保たれるため、導入時に `generatePlurals` を使っても安全です。これらの結果をすべてプレビューするには、[`verbatra diff`](https://verbatra.kreitz-webdev.de/ja/docs/cli/diff.md) または `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`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#lock_contended) で止まり、何も書き込まれません。

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

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

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

<AvailableFrom version="0.12.0" />

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

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

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

## 欠落または破損 [#欠落または破損]

ロックファイルがない場合はエラーではなく、[初回の実行](#既存プロジェクトへの導入)として扱われます。解析できない、構造が正しくない、大きすぎる、またはサポートされないバージョンのロックファイルは、上書きされずに [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#lock_file_invalid) で実行が失敗します。そのため、ベースラインを失わずに復元できます。

## 来歴：各値を誰が書いたか [#来歴各値を誰が書いたか]

<AvailableFrom version="0.12.0" />

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

| 出どころ | 書いた主体 |
| --- | --- |
| `machine` | `translate`、`watch`、単一キーの再翻訳でのプロバイダーの回答（プロバイダーの `id` と、わかる場合はモデルを含む） |
| `memory` | 完全一致のキャッシュヒット。人手のみの実行（プロバイダー `none`）が埋めるすべての値を含む |
| `fuzzy` | [あいまい一致のキャッシュ](https://verbatra.kreitz-webdev.de/ja/docs/the-cache.md#あいまい一致による再利用)のヒット |
| `human` | SDK の `editEntry` による人の編集（Studio の編集ダイアログが行うもの） |
| `agent` | `actor: "agent"` を指定した `editEntry` による AI エージェントの編集 |
| `import` | `verbatra import` で受け入れられた行 |
| `unknown` | 記録のなかった値へのレビューの判断、またはこのリリースが知らない出どころ |

さらに 2 つは、読み取り時に導き出されます。`unrecorded` は記録がない値で、アップグレード後はすべてのキーがこれに当たります。`external` は、翻訳者の pull request、古い verbatra、マージなど、verbatra の外で値が変更されたために、記録のハッシュと一致しなくなったものです。各読み取りが返すフィールドは [SDK リファレンス](https://verbatra.kreitz-webdev.de/ja/docs/sdk/inspect.md#loadprovenance)にあります。

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

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

改ざん防止にはなっていません。レポートにするには、[機械翻訳の証跡を記録する](https://verbatra.kreitz-webdev.de/ja/docs/provenance-evidence.md)を参照してください。

### レビューの判断 [#レビューの判断]

<AvailableFrom version="0.12.0" />

記録には、`approved` または `rejected` のレビューの判断を、任意の `reviewer` 名とともに持たせられます。これを書き込むのは、Studio の **Review**（レビュー）ページ（[Studio でレビューする](https://verbatra.kreitz-webdev.de/ja/docs/review-in-studio.md)）、SDK のレビュー関数（[レビューと再翻訳](https://verbatra.kreitz-webdev.de/ja/docs/sdk/review.md)）、MCP のレビューツール（[`verbatra mcp`](https://verbatra.kreitz-webdev.de/ja/docs/cli/mcp.md)）です。MCP のツールは人の判断を中継するため、その人の名前が必須です。判断は、レビュー担当者が見たその値そのものに対して適用されます。値が変更されていた場合、判断は拒否されます。

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

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

判断はコミットされるこのファイルに保存されます。そのため、レビューキューと [`verbatra check --require-reviewed`](https://verbatra.kreitz-webdev.de/ja/docs/cli/check.md#レビュー済みの訳文を必須にする) はどこでも同じ状態を参照し、`reviewer` の名前は公開されます。verbatra がこの名前を自動で入力することはありません。

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

`verbatra.lock.json` と `verbatra.provenance.json` をロケールファイルと一緒にコミットし、手で編集しないでください。この 2 つは、チームと CI が差分を取る基準であり、[ロールバック](https://verbatra.kreitz-webdev.de/ja/docs/recovery-and-rollback.md)が復元する対象です。
