---
title: "翻訳の安全性"
description: "安全性の仕組みを説明します。信頼できない文字列、整合性ゲート、レビューフラグ、トークン予算、情報を漏らさないエラーを扱います。"
type: "concept"
---
# 翻訳の安全性

安全性の仕組みを説明します。信頼できない文字列、整合性ゲート、レビューフラグ、トークン予算、情報を漏らさないエラーを扱います。

verbatra は、翻訳する文字列も、プロバイダーが返す内容も信頼しません。

| 層 | 防ぐもの | 失敗時 |
| --- | --- | --- |
| プロンプトインジェクションの境界 | 指示のように読める文字列 | 失敗しません（文字列は常にデータとしてのみ扱われます） |
| 整合性ゲート | 壊れたプレースホルダー、ICU、マークアップ、空の値や崩れた値 | キーを保留し、次回の実行で再試行します |
| レビューフラグ | 有効だが疑わしい値 | キーは書き込まれ、人のレビュー待ちになります |
| トークン予算 | 設定した上限を超える費用 | 実行の残りが保留されるか、フラグが付きます |
| 構造化されたエラー | API キーやヘッダーがメッセージに漏れること | 固定メッセージを持つ安定したコードになります |

## 信頼できない文字列とプロンプトインジェクションの境界 [#信頼できない文字列とプロンプトインジェクションの境界]

翻訳対象の文字列には、指示のように見えるテキスト（「指示を無視して」など）が含まれる場合があります。そのため verbatra は、すべての文字列を信頼できない入力として扱います。LLM プロバイダーに送るシステムルールは、コンパイル時の定数です。変化する内容はすべて、ユーザーターンの JSON ペイロードにだけ載せて送ります。エントリ、用語集、トーン、言語名、複数形のターゲットカテゴリがこれに当たります。指示のチャネルには載せません。レスポンスは固定のスキーマに一致する必要があります。要求していないキーがレスポンスに含まれていると、そのサブバッチ全体が失敗します。

### 言語名、文字体系名、地域名 [#言語名文字体系名地域名]

<AvailableFrom version="0.12.0" />

ロケールコードだけでは足りない場合があります。`sr-Latn` はキリル文字で返ってくることが多く、`pt-BR` と `pt-PT` も区別があいまいになります。そこで LLM プロバイダーには、各言語の英語名、文字体系、地域も渡します。これらは、設定ファイルのロケールに対して Node.js から取得します。`localeMap` が別のコードを送る場合も同じです。これらはデータとして送られます。固定のシステムルールの 1 つが、指定された文字体系と地域バリアントで書くようモデルに求めます。これらは[翻訳キャッシュ](https://verbatra.kreitz-webdev.de/ja/docs/the-cache.md)のフィンガープリントには含まれません。Node.js が名前を付けられないコード（私用コードの `qaa` など）は、名前なしで送られます。

## 整合性ゲート [#整合性ゲート]

スキーマに合っている訳文でも、壊れていることがあります。そこで 1 つのゲートが、候補訳そのものを見て受け入れるかどうかを決めます。プロバイダー自身の報告は信頼しません。同じゲートが、すべての書き込み経路で動きます。プロバイダーの回答、キャッシュヒット、ブックのインポート行、Studio で入力した編集が対象です。ソースが同じ複数のキーで共有される値は、キーごとに、そのキー自身のソースに対してゲートを通ります。

| チェック | 候補訳が拒否される条件 |
| --- | --- |
| プレースホルダー | プレースホルダーがソースと異なる場合です。多重集合として比較するため、個数は結果に影響しますが、順序は影響しません。何をプレースホルダーとみなすかは、[フォーマット](https://verbatra.kreitz-webdev.de/ja/docs/formats.md)ごとに定義されています。 |
| ICU | next-intl と ARB では、ICU メッセージとして解析できなくなった場合、または複数形の分岐がターゲット言語に合わない場合です（後述）。比較は分岐ごとに行うため、複数形の 1 つの分岐の中に作り出されたプレースホルダーも検出できます。 |
| 余分な記号 | i18next、ngx-translate、YAML では、ソースにない `{name}` の形をした記号が加わった場合です。記号が減るのは許可されます。これらのフォーマットでは波括弧 1 つはリテラルなテキストだからです。 |
| インラインマークアップ | HTML や XML のタグがソースと異なる場合、または対応が取れていない場合です（後述）。 |
| 崩れた出力 | 繰り返しのループになっている場合、または長さがソースから大きく外れた場合です。 |
| 空の値 | ソースが空でないのに、空または空白だけの場合です。訳文を空にするのは意図的な操作です。ブックの `[[CLEAR]]` という特殊値で行います（[Excel や CSV で受け渡す](https://verbatra.kreitz-webdev.de/ja/docs/manual-translation.md)）。 |

候補訳が複数のチェックに違反していても、拒否の理由は 1 つです。理由は、`empty`、`icu`（解析できない）、`placeholder`、`markup`、`icu`（分岐）、`degenerate` の順で最初に当てはまるものです。各理由と、verbatra が一緒に出力する詳細は、[整合性による拒否の理由](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#integrity-refusal-reasons)に一覧があります。

ゲートが保証するのは、拒否された値が書き込まれないことです。拒否された値は、実行サマリーに整合性の不一致として表示されます。[ロックファイル](https://verbatra.kreitz-webdev.de/ja/docs/the-lock-file.md)には以前のハッシュが残り、次回の実行で再試行されます。訳文がまったく得られなかったキー（プロバイダーの呼び出しが失敗した場合や、1 回の修復リクエストの後もキーが欠落していた場合）は、代わりにプロバイダーの失敗として報告され、同じように再試行されます。ソース側では、値自体が不正な ICU であるキーは、翻訳の前に除外されます。

ゲートが保証しないのは、訳文が正しいことです。証明するのは構造であり、意味ではありません。

### ターゲット言語ごとの複数形の分岐 [#ターゲット言語ごとの複数形の分岐]

<AvailableFrom version="0.12.0" />

ICU の複数形には、その言語の CLDR 複数形カテゴリごとに 1 つの分岐があります（[例](https://verbatra.kreitz-webdev.de/ja/docs/language-support.md#複数形)）。next-intl と ARB では、verbatra は Node.js に組み込まれた CLDR のデータからターゲット言語のカテゴリを読み取ります。

- LLM プロバイダーには、まさにそれらの分岐を求めます（`plural` は基数、`selectordinal` は序数です）。カテゴリはデータとして送られるため、インジェクションの境界は変わりません。
- ゲートは、必要な分岐が足りない `plural` や `selectordinal`、またはその言語にない分岐が残っているものを、すべての書き込み経路で拒否し、誤っている各分岐を示します。
- `=0` のような完全一致の分岐は、すべて残す必要があります。訳文が完全一致の分岐を追加するのは構いません。`select` の分岐はコード側のキーなので、訳文はソースと完全に同じものを保ちます。
- Node.js に複数形ルールがないロケールでは、`other` だけが必須です。

このチェックの導入前に書き込まれた値（`many` がないフランス語の複数形など）は、ソースが変わるまでそのまま残ります。現在は [`verbatra check --qa`](https://verbatra.kreitz-webdev.de/ja/docs/cli/check.md#品質チェック) で検出できます。

### インラインマークアップの一致 [#インラインマークアップの一致]

<AvailableFrom version="0.11.0" />

インラインタグが欠けたり壊れたりすると、描画が崩れます。i18next の `Trans` ブロック内の `<b>`、Android の `<string>` 内のエスケープされた `&lt;b&gt;`、gettext の `<a href>` が例です。そのためゲートは、タグと属性の名前を多重集合として比較します。

- **拒否**：タグの欠落、追加、名前の変更。属性名の集合の変更（`dir` の追加も含む）。対応が取れていないマークアップや、入れ子が誤っているマークアップ。2 つのタグが 1 つに統合された場合。
- **許可**：同じタグを別の順序にした場合。`title` や `alt` などの属性値を翻訳した場合。`<br>` を `<br/>` と書いた場合。
- **保護される値**：URL 属性はスキームとホストを保つ必要があります（`/docs` が `/de/docs` になるのは許可され、`https://evil.example/docs` は許可されません）。`javascript:` の URL は拒否されます。`style`、イベントハンドラー、`<meta content>` などの値は、ソースとまったく同じでなければなりません。
- **翻訳されない**：`script`、`style` などの要素の内容は、変更なしで返す必要があります。周囲のテキストを翻訳するには、そのようなタグを文中でエスケープします（`&lt;script&gt;`）。

マークアップのない文字列にマークアップが作り出された場合も拒否されます。一方、`<Enter>` のような山かっこ付きの普通の語は、テキストとして読み取られます。フォーマットがすでにプレースホルダーとして報告するタグは、プレースホルダーのチェックに任せます。コメント、生のテキスト、不正な形式のソースについては、[`markup`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#markup) を参照してください。

## レビューフラグ [#レビューフラグ]

2 つ目の層は警告のみの層で、疑わしい結果に人のためのフラグを付けます。フラグがキーを保留することはありません。値は書き込まれ、ロックファイルに記録され、その実行の `needsReview` に載り、レビューキューに残ります。

| 理由 | フラグが付く訳文 |
| --- | --- |
| [`LENGTH_RATIO_OUTLIER`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#length_ratio_outlier) | 文字体系に応じて重み付けすると、ソースより極端に短いか長い訳文です |
| [`MAX_LENGTH_EXCEEDED`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#max_length_exceeded) | キーの [`maxLength`](https://verbatra.kreitz-webdev.de/ja/docs/config-file.md#maxlength) の上限より長い訳文です <AvailableFrom version="0.11.0" /> |
| [`EQUALS_SOURCE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#equals_source) | 前後の空白を除いて、ソーステキストと同一の訳文です |
| [`GLOSSARY_TERM_MISSED`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#glossary_term_missed) | 用語集の用語の訳が使われていない、または翻訳禁止の用語が変更されている訳文です |
| [`GLOSSARY_FORBIDDEN_TERM`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#glossary_forbidden_term) | 用語集が禁止する訳語を使っている訳文です <AvailableFrom version="0.12.0" /> |
| [`INTEGRITY_REORDERED`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#integrity_reordered) | プレースホルダーはすべて残っているが、順序が変わっている訳文です |
| [`PROVIDER_DEGRADED`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#provider_degraded) | プロバイダーの機能が低下したバッチから得られた訳文です（丁寧さの指定が無視された場合など） |
| [`FUZZY_CACHE_REUSE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#fuzzy_cache_reuse) | [編集された類似のソースから再利用された](https://verbatra.kreitz-webdev.de/ja/docs/the-cache.md#あいまい一致による再利用)訳文です <AvailableFrom version="0.11.0" /> |
| [`FOREIGN_PLACEHOLDER_CHANGED`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#foreign_placeholder_changed) | [フォーマット](https://verbatra.kreitz-webdev.de/ja/docs/formats.md)が展開しない、プレースホルダーのような記号（i18next の `{name}` など）が削除または変更されている訳文です <AvailableFrom version="0.12.0" /> |
| [`BIDI_CONTROLS_CHANGED`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#bidi_controls_changed) | 方向制御文字が閉じられていない、またはテキストを反転させるオーバーライドが追加されている訳文です <AvailableFrom version="0.12.0" /> |

DeepL、Google、LibreTranslate では、このような記号はマスクされます。マスクも復元もできない値は保留されます（[`PLACEHOLDER_UNSUPPORTED`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#placeholder_unsupported)）。このフラグが対象にするのは、LLM と人が書いた訳文です。

キャッシュヒットと共有される値にも、新しい訳文と同じようにフラグが付きます。フラグが付いたキーは、実行サマリーの `needsReview`、ブックのレビュー列、[Studio の Review ページ](https://verbatra.kreitz-webdev.de/ja/docs/review-in-studio.md)に表示されます。人が値を承認、却下、または書き直すまで続きます（[レビューの判断](https://verbatra.kreitz-webdev.de/ja/docs/the-lock-file.md#レビューの判断)）。

## トークン予算 [#トークン予算]

`maxTokens` は、実行全体のトークンを、すべての呼び出しとロケールにわたって数えます。`budgetBehavior: "stop"` では、上限を超えそうになった時点で実行の残りを保留し、次回の実行で再試行します（[ルール](https://verbatra.kreitz-webdev.de/ja/docs/config-file.md#maxtokens-と-budgetbehavior)）。

予算が保証するのは、上限に達する前に終わった作業が書き込まれてロックファイルに記録されたままになり、中途半端に書き込まれたものが残らないことです。保証しないのは次の点です。処理中のリクエストは、見込みより多く費用がかかる場合があります。上限が制限するのは 1 回の実行であり、`watch` セッション全体ではありません。Studio やエージェントによる再翻訳も対象外です。

## エラーから情報は漏れない [#エラーから情報は漏れない]

プロバイダーの呼び出しが失敗すると、verbatra は生の SDK エラー（リクエストヘッダーや認証情報を含む場合があります）を破棄し、ログに出力することも、再スローすることもありません。代わりに verbatra は、安定した[コード](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#provider-error-codes)と、シークレットを含まない固定メッセージを持つ構造化されたエラーをスローします。API キーの秘匿化については、[データの取り扱いとプライバシー](https://verbatra.kreitz-webdev.de/ja/docs/data-handling.md#api-キー)を参照してください。

## 確認できる場所 [#確認できる場所]

ここまでの内容はすべて、ロケールごとに[実行サマリー](https://verbatra.kreitz-webdev.de/ja/docs/sdk/run-summary.md)のデータとして得られます。1 つのロケールが失敗しても、ほかのロケールは止まりません。

### コミット済みの値 [#コミット済みの値]

<AvailableFrom version="0.12.0" />

[`verbatra check --qa`](https://verbatra.kreitz-webdev.de/ja/docs/cli/check.md#品質チェック) は、プロバイダーを呼び出さずに、コミット済みの値に対してゲートとレビューフラグを実行します。

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

- [実行の仕組み](https://verbatra.kreitz-webdev.de/ja/docs/how-it-works.md)：各チェックが処理の流れのどこにあるかを説明します。
- [データの取り扱いとプライバシー](https://verbatra.kreitz-webdev.de/ja/docs/data-handling.md)：マシンの外に出るものを説明します。
