---
title: "実行の仕組み"
description: "ソースロケールの読み込みと変更されたキーの検出から、訳文の書き込みとロックファイルの更新まで、翻訳処理の流れ全体を説明します。"
type: "concept"
---
# 実行の仕組み

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

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

<DiffPanel />

## ソースロケールを読み込む [#ソースロケールを読み込む]

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

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

実行が差分のみで済むのは、この比較があるためです。verbatra は既存のターゲットファイルを読み込み（ファイルがなければ空として扱いますが、`xliff` と `apple-xcstrings` のライターはターゲットがないと拒否します）、各ソースキーをロックファイル（[ロックファイルと来歴](https://verbatra.kreitz-webdev.de/ja/docs/the-lock-file.md)を参照）と比較します。ロックファイルは、以前に翻訳した内容の記録です。

| 分類 | 意味 | 実行の動作 |
| --- | --- | --- |
| missing | ターゲットにキーがない | 翻訳する |
| changed | ソースが記録されたハッシュと一致しなくなった | 翻訳する |
| unchanged | ソースが記録されたハッシュと一致している、または記録がない | そのままにする |
| empty source | ソースの値が空白 | スキップして別に数える |
| orphaned | キーがターゲットにあり、ソースにない | 報告する。削除は `--prune` または `prune: true` のときだけ |

### 据え置かれたキー [#据え置かれたキー]

<AvailableFrom version="0.12.0" />

翻訳の対象になるキーのうち、2 種類は据え置かれます。現在の値を人が書いた、またはインポートした変更済みキーは、デフォルトで保護されます（`humanEdits`）。`pinnedKeys` に一致するキーは、一切機械翻訳されません。どちらも、人が対応するまで古いままです。詳しくは[人手翻訳を保護する](https://verbatra.kreitz-webdev.de/ja/docs/protecting-human-translations.md)を参照してください。

## プロバイダーにバッチで送る [#プロバイダーにバッチで送る]

すべての候補訳は、まず[翻訳キャッシュ](https://verbatra.kreitz-webdev.de/ja/docs/the-cache.md)で検索されます。ヒットした値は再利用され、プロバイダーには届きません。キャッシュミスしたキーのうち、ソースの内容が同じものはまとめられます。そのため、同じテキストはキーごとではなく、ロケールごとに 1 回のリクエストで済みます。

グループは、最大 `maxBatchSize` 件（デフォルトは 50）のサブバッチに分けて、順番にプロバイダーへ送られます。各サブバッチには、エントリ、そのロケールの用語集の用語、`tone` が含まれます。サブバッチが失敗した場合（レート制限、タイムアウト、取り消された API キー）、そのキーは今回の実行では保留され、残りのサブバッチは処理を続けます。各プロバイダーがこれらの入力をどう使うかは、[プロバイダー](https://verbatra.kreitz-webdev.de/ja/docs/providers.md)で説明しています。

## レスポンスを検証する [#レスポンスを検証する]

プロバイダーの出力はデータであり、自由なテキストではありません。LLM プロバイダーの場合、レスポンスは固定のスキーマに一致する必要があります。

- 形式が不正なレスポンス、またはリクエストしていないキーを含むレスポンスでは、サブバッチ全体が失敗します。
- リクエストしたキーが欠けている、または重複している場合は、もう一度リクエストされます。
- その後も解決しないキーは、今回の実行では翻訳されません。

機械翻訳プロバイダーにはレスポンススキーマがありませんが、結果は同じ整合性ゲートを通ります。

## 整合性ゲートを実行する [#整合性ゲートを実行する]

スキーマに合っている訳文でも、壊れていることがあります。そのため verbatra は、プロバイダー自身の報告を信用せず、候補訳そのものから受け入れるかどうかを判断します。プレースホルダーが失われた候補訳、ICU メッセージやマークアップが壊れた候補訳、空で返ってきた候補訳、崩れた出力になった候補訳は、書き込まれずに保留されます。チェックの内容は[翻訳の安全性](https://verbatra.kreitz-webdev.de/ja/docs/translation-safety.md#整合性ゲート)にあります。

## アダプター経由で書き込む [#アダプター経由で書き込む]

受け入れられた訳文はターゲットにマージされ、フォーマットアダプターがアトミックに、安定したキーの順序で書き込みます。ターゲットにすでにあるキーは位置を保ち、新しいキーは既存のキーの後ろにソースの順序で追加されます。中断された書き込みで、書きかけのファイルが残ることはありません。pull request をレビューする人が見る差分は、小さく安定しています。

## ロックファイルを更新する [#ロックファイルを更新する]

ロケールの書き込みが終わると、そのロックファイルのエントリが現在のソースのハッシュで更新されます。今回の実行で保留されたキーは以前のハッシュを保つため、次回の実行でも作業が必要なキーとして扱われます。各ロケールはプロセス間の[書き込みロック](https://verbatra.kreitz-webdev.de/ja/docs/the-lock-file.md#書き込みロック)の下で書き込まれます。そのため、重なった 2 つの実行が古いベースラインと比較したり、同じ呼び出しに 2 回費用を払ったりすることはありません。

## ロケールは 1 つずつ、失敗はデータとして [#ロケールは-1-つずつ失敗はデータとして]

各ターゲットロケールは個別に実行され、1 つのロケールが失敗してもほかのロケールは止まりません。実行はロケールごとのサマリーを返します。サマリーには、翻訳済み、未変更、孤立、保留、レビューのフラグ付き、通知が含まれます。各フィールドの内容は [RunSummary](https://verbatra.kreitz-webdev.de/ja/docs/sdk/run-summary.md) にあります。

この設計が保証するのは次の点です。

- ソースを編集しない 2 回目の実行では、プロバイダーを一切呼び出しません。
- チェックが拒否した値は書き込まれず、保留された値が完了として記録されることもありません。
- ドライラン（`--dry-run`）は差分の後で止まり、同じ形のサマリーを返します。プロバイダーを生成せず、ファイルも書き込みません。

一方、この設計は訳文の良し悪しを判断しません。その判断は[レビューフラグ](https://verbatra.kreitz-webdev.de/ja/docs/translation-safety.md#レビューフラグ)と人が担います。

## 関連項目 [#関連項目]

- [`verbatra translate`](https://verbatra.kreitz-webdev.de/ja/docs/cli/translate.md)：実行のオプション、出力、終了コード
- [ロックファイルと来歴](https://verbatra.kreitz-webdev.de/ja/docs/the-lock-file.md)：ベースラインが記録する内容
- [翻訳キャッシュ](https://verbatra.kreitz-webdev.de/ja/docs/the-cache.md)：再利用のキーの決め方
- [翻訳の安全性](https://verbatra.kreitz-webdev.de/ja/docs/translation-safety.md)：整合性ゲートとレビューフラグ
- [エラーコード](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md)：実行が報告しうるすべてのコード
