ドキュメント / コンセプト
機械翻訳されたページ
翻訳キャッシュ
verbatra.cache.json が実行間で再利用するもの、フィンガープリントが各エントリを設定に結び付ける仕組み、キャッシュの問題で実行が失敗しない理由を説明します。
翻訳キャッシュ verbatra.cache.json は、コンテンツをキーにしたローカルの翻訳メモリです。ソーステキストの訳文を、どのキーが保持していても覚えておくため、同じテキストに二度費用がかかることはありません。ロックファイルと来歴が答えるのは「このキーは最新か」で、キャッシュが答えるのは「このテキストを前に翻訳したことがあるか」です。
再利用されるもの
キーをプロバイダーに送る前に、verbatra は現在のソースエントリのハッシュを検索します。ハッシュの対象は、テキストに加えて、説明、意味、複数形のフラグ、プレースホルダーです。ヒットすれば費用はかかりません。検索はコンテンツ単位で行うため、ロックファイルでは見えない変更をまたいで再利用できます。
- 名前を変えたキー:
home.titleをlanding.titleに移しても、訳文は再利用されます。 - 重複したコンテンツ:ソーステキストとコンテキストが同じ 2 つのキーは、1 つの訳文を共有します。
再利用された値は、そのまま信用されるわけではありません。新しい訳文と同じように、現在のソースに対して整合性ゲートを通ります。合わなくなった値は破棄され、翻訳し直されます。キャッシュヒットは、今回の実行で翻訳されたキーとは別に、ロケールごとに報告されます。
レビュー担当者が却下した値は、そのキーには二度と再利用されません。来歴ファイルが却下されたテキストのハッシュを保持していて、実行はそれに一致するヒットを飛ばします。唯一の例外は、実行が読み取れない来歴ファイルです(より新しいバージョンの verbatra が書いたものや、humanEdits: "overwrite" で読み込んだ壊れたもの)。この場合、実行は却下の記録を知りません。
フィンガープリント
すべてのエントリは、作られたコンテキストに結び付けられます。フィンガープリントの対象は、プロバイダー、モデル、そのロケールのトーン、そのロケールの用語集の用語、そしてプロバイダーの localeMap(エントリがある場合)です。どれかを変えると以前のエントリは一致しなくなるため、トーンを変えたり用語集を編集したりしても、キャッシュは古い結果を返しません。すでに書き込まれた値は、翻訳し直すまでそのままです。用語集の部分は、sensitiveData の設定が用語を保留または秘匿化した後に、verbatra がプロバイダーに送る用語です。設定したプロバイダーが用語集の用語を使うかどうかは問いません(DeepL、Google Cloud Translation、LibreTranslate は無視します)。そのため、用語を編集すれば翻訳し直されます。用語の caseSensitive フラグは対象に含まれません。フィンガープリントはロケールごとに別々なので、用語集の用語のドイツ語訳だけを編集しても、フランス語のエントリは一致したままです。
フォーマットはフィンガープリントに含まれません。ヒットのたびに整合性ゲートが働くため、合わなくなった値はそこで捕捉されます。プロバイダーが none の場合、すべてのエントリは、トーンと用語集の影響を受けない人手のみの 1 つの区画に入ります。
あいまい一致による再利用
完全一致のヒットには、ソーステキストのハッシュが以前と同じ値になる必要があるため、1 文字でも編集するとキャッシュミスになります。fuzzyCache は、その場合のためにオプトインで使えるフォールバックです。キーがミスしたとき、verbatra はそのソースを、同じロケールかつ同じフィンガープリントのほかのエントリと比較してスコアを付け、threshold 以上でもっとも近いものを再利用します。スコアは、1 から文字単位の編集距離を長いほうの文字列の長さで割った値を引いたもので、1 は同一を意味します。
しきい値は安全設定ではない
文字の距離は意味ではありません。「not」を消す、「cannot」を「can」に変える、ブランド名を別のものに入れ替えるといった小さな編集ですが、スコアは 0.9 を超え、しかも文の意味を逆にします。しきい値が決めるのは、避けられるプロバイダーの費用の大きさで、再利用の安全性ではありません。安全性は、この数値に左右されないルールから得られます。
- オプトイン:オンにしない限りオフです。
- レビューのフラグ:あいまい一致による再利用には、スコアにかかわらず、実行のたびに
FUZZY_が付きます。レビューキュー(Studio では Review queue)を誰も処理しないなら、オフのままにしてください。CACHE_ REUSE - 数字の変化:数字が変わっていると、再利用を拒否します。2 つのソースで数字の個数、値、順序が違う場合、そのエントリは候補になりません。対象は Unicode のすべての数字文字です(
m²からm³、½から¼)。ただし、単語で書かれた数は対象外です。 - 再利用では決着しない:ロックファイルにはキーの古いベースラインが残るため、キーは変更されたままです。実際の訳文が入るまで、以降の実行でもプロバイダーの費用をかけずに再び提案され、
checkも報告し続けます。 - 変更のないソーステキスト:あいまい一致の層には届きません。説明や複数形のフラグだけを編集した場合、キーはこれまでどおりプロバイダーに送られます。
あいまい一致による再利用が保証しないこと
あいまい一致による再利用は、もうソースではないテキストの訳文です。そのため、完全一致のヒットとして示されることはありません。
- ほかの候補訳と同じく整合性ゲートを通ります。プレースホルダーが合わなくなった近い一致は拒否され、キーはプロバイダーに送られます。
- 完全一致のヒットとは別に、
fuzzy-reusedとして、キー、スコア、以前のソーステキストとともに報告されます。SDK ではLocaleSummary.fuzzyHitsが同じ内容を持ちます。 - キャッシュには書き戻されないため、後の実行が完全一致のヒットと取り違えることはありません。
スコアの計算は 1 つのフィンガープリントの中に限られ、上限があります。キーごとに最大 256 件の候補までで、2,000 文字を超えるソーステキストは飛ばされます。プロバイダーが none の場合、あいまい一致は適用されません。
ファイル
verbatra.cache.json は、ロックファイルの隣に置かれる、再生成できるローカルのファイルです。バージョン管理には含めないでください。共有のベースラインではなく、費用の最適化のためのものです。verbatra init はこのファイルを .gitignore に追加します。translate、watch、import、tmx import、pseudo は、このエントリがない既存の .gitignore に追加し、その旨を stderr に出力します。
キャッシュが原因で実行が失敗することはありません。ファイルがない、壊れている、大きすぎる場合は、空のキャッシュとして扱われ、再構築されます。より新しいバージョンの verbatra が書いたファイルも、その実行では空として扱われますが、ディスク上にはそのまま残り、通知が出ます。最初からやり直すには、ファイルを削除します。あいまい一致のスコア計算のために、ファイルは各ソース文字列を訳文の隣に保存します。そのため、サイズはおおよそソーステキストの大きさまで増えます。
ツール間で翻訳メモリを移す
verbatra tmx は、ほかの翻訳ツールの TMX ファイルをキャッシュにインポートし、キャッシュを TMX としてエクスポートします。インポートされた翻訳単位は現在のフィンガープリントで保存されるため、ほかのエントリと同じく、プロバイダー、モデル、トーン、verbatra が送る用語集の用語、localeMap のどれかが変わると一致しなくなります。「削除すれば再構築される」には 1 つ注意点があります。インポートした翻訳メモリは、元の TMX ファイルの範囲でしか復元できません。そのファイルは残しておいてください。
キャッシュを使わない
translate または watch に --no-cache を付けると(SDK では cache: false)、あいまい一致による再利用も含めてキャッシュを使わず、キャッシュのない実行とまったく同じようにプロバイダーを呼び出します。ファイルには手を付けません。完全一致の再利用は残し、あいまい一致のフォールバックだけをやめるには、設定に fuzzyCache を書きません。ドライランはキャッシュを書き込まず、読み取るのもプロバイダーが none のときだけです。そのため、計画は本番の実行と一致します。
制限事項
generatePlurals が合成した複数形はキャッシュされないため、常にプロバイダーから取得されます。
関連項目
fuzzyCache:設定キーとその範囲です。verbatra tmx:翻訳メモリを TMX でインポートおよびエクスポートします。- 実行の仕組み:キャッシュの検索が処理の流れのどこにあるかを説明します。
- 実行前に費用を見積もる:費用をかける前にキャッシュが節約する内容です。