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

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

機械翻訳されたページ

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

翻訳の安全性

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

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

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

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

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

言語名、文字体系名、地域名

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

整合性ゲート

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

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

候補訳が複数のチェックに違反していても、拒否の理由は 1 つです。理由は、empty、icu(解析できない)、placeholder、markup、icu(分岐)、degenerate の順で最初に当てはまるものです。各理由と、verbatra が一緒に出力する詳細は、整合性による拒否の理由に一覧があります。

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

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

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

ICU の複数形には、その言語の CLDR 複数形カテゴリごとに 1 つの分岐があります(例)。next-intl と ARB では、verbatra は Node.js に組み込まれた CLDR のデータからターゲット言語のカテゴリを読み取ります。

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

このチェックの導入前に書き込まれた値(many がないフランス語の複数形など)は、ソースが変わるまでそのまま残ります。現在は verbatra check --qa で検出できます。

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

インラインタグが欠けたり壊れたりすると、描画が崩れます。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 を参照してください。

レビューフラグ

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

理由フラグが付く訳文
LENGTH_RATIO_OUTLIER文字体系に応じて重み付けすると、ソースより極端に短いか長い訳文です
MAX_LENGTH_EXCEEDEDキーの maxLength の上限より長い訳文です
EQUALS_SOURCE前後の空白を除いて、ソーステキストと同一の訳文です
GLOSSARY_TERM_MISSED用語集の用語の訳が使われていない、または翻訳禁止の用語が変更されている訳文です
GLOSSARY_FORBIDDEN_TERM用語集が禁止する訳語を使っている訳文です
INTEGRITY_REORDEREDプレースホルダーはすべて残っているが、順序が変わっている訳文です
PROVIDER_DEGRADEDプロバイダーの機能が低下したバッチから得られた訳文です(丁寧さの指定が無視された場合など)
FUZZY_CACHE_REUSE編集された類似のソースから再利用された訳文です
FOREIGN_PLACEHOLDER_CHANGEDフォーマットが展開しない、プレースホルダーのような記号(i18next の {name} など)が削除または変更されている訳文です
BIDI_CONTROLS_CHANGED方向制御文字が閉じられていない、またはテキストを反転させるオーバーライドが追加されている訳文です

DeepL、Google、LibreTranslate では、このような記号はマスクされます。マスクも復元もできない値は保留されます(PLACEHOLDER_UNSUPPORTED)。このフラグが対象にするのは、LLM と人が書いた訳文です。

キャッシュヒットと共有される値にも、新しい訳文と同じようにフラグが付きます。フラグが付いたキーは、実行サマリーの needsReview、ブックのレビュー列、Studio の Review ページに表示されます。人が値を承認、却下、または書き直すまで続きます(レビューの判断)。

トークン予算

maxTokens は、実行全体のトークンを、すべての呼び出しとロケールにわたって数えます。budgetBehavior: "stop" では、上限を超えそうになった時点で実行の残りを保留し、次回の実行で再試行します(ルール)。

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

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

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

確認できる場所

ここまでの内容はすべて、ロケールごとに実行サマリーのデータとして得られます。1 つのロケールが失敗しても、ほかのロケールは止まりません。

コミット済みの値

verbatra check --qa は、プロバイダーを呼び出さずに、コミット済みの値に対してゲートとレビューフラグを実行します。

関連項目

GitHub で編集

このページの内容