翻訳APIワークフローを構築する

アプリケーションのレコードをサーバー上で翻訳し、採用した各言語版を、対応する原文のリビジョンに紐づけて管理します。

編集者が商品説明を更新したら、各翻訳版にも変更を反映する必要があります。APIのレスポンスで新しいテキストは取得できますが、それがどのレコードに属するか、原文が今も最新か、いつ読者に公開するかは、アプリケーションが判断します。

このガイドでは、初めての翻訳リクエストを、繰り返し実行できるバックエンドのワークフローへと発展させます。商品説明やヘルプ記事など、アプリケーションが管理するレコードに適した方法です。一方、静的なアプリケーションリソースには、CIファイルワークフローのほうが適している場合が多くあります。リソースのコンパイルやリポジトリのレビューを通じて、すでに検証する機会が設けられているためです。

ひとまとまりのコンテンツを送信する #

商品レコードを表す単一のインラインJSONドキュメントで、ローカライゼーションジョブを作成します。関連するフィールドをまとめ、コンテキストでそれぞれの用途を説明できるようにします。また、キーを固定し、ダウンロードしたオブジェクトを元のフィールドに対応づけられるようにします。

APIキーと、このリビジョンで一貫して使うIdempotency-Keyを指定して、次のリクエスト本文をPOST /v2/organizations/:orgId/localization/jobsに送信します。

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "products/bottle.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Product listing for a reusable drinks bottle",
          "hints": {
            "$.title": ["Catalog card title"],
            "$.description": ["Short product description; do not add specifications"]
          }
        }
      },
      "source": {
        "content": {
          "title": "Insulated bottle",
          "description": "Keeps drinks cold during your commute."
        }
      }
    }
  ]
}

認証情報はバックエンドで管理し、エンジンは明示的に選択します。製品用語には共通の用語集の指針を適用し、今回の用途はドキュメントのコンテキストで伝えます。ヒントと保護対象のパスについては、JSONリファレンスを参照してください。

バックグラウンド処理で翻訳を実行する #

返されたジョブIDを保存してから、ジョブを開始します。uploadsに記載されたものをすべてアップロードし、その後でPOST /v2/localization/jobs/:id/startを呼び出します。インラインJSONの場合も、この明示的な開始操作が必要です。

バックエンドのワーカーからジョブをポーリングし、完了した翻訳先の成果物を、返されたURLからダウンロードします。アプリケーションがこの処理を永続化されたキューに登録した時点で、編集者の保存リクエストには応答を返せます。翻訳や人によるレビューが終わるまで、リクエストを開いたままにする必要はありません。

差分更新では、前回の原文と採用済みの訳文の成果物を保持し、次のドキュメントリクエストで指定します。再利用できる範囲については、ドキュメントの更新で説明しています。

原文を保存してから作業を記録する #

原文のトランザクションがコミットされた後で、コンテンツID、原文のリビジョン、翻訳先ロケール、ローカライゼーションエンジンと設定のレコード、処理状態を含む作業レコードを、アプリケーション側のストレージに作成します。そのレコードを基に翻訳をキューに追加します。これにより、後からトランザクションのロールバックで取り消される編集内容を、ワーカーが翻訳してしまうのを防げます。

処理結果は翻訳先言語ごとに保持します。ドイツ語は準備が整っていても、フランス語は再試行やレビューが必要かもしれません。全体で一つの「翻訳済み」フラグだけを記録すると、何を配信するか判断するアプリケーションが、その違いを把握できなくなります。独自に追加する状態名はアプリケーション側の設計であり、APIのレスポンスで定義された用語ではありません。

対象のリビジョンに対応する出力だけを採用する #

原文を編集した順序と、翻訳が完了する順序は一致するとは限りません。次の流れを考えてみましょう。

イベントアプリケーションの動作
リビジョン12が保存されるリビジョン12のドイツ語翻訳をキューに追加する。
その処理が完了する前にリビジョン13が保存されるリビジョン13をキューに追加し、現在の原文として設定する。
リビジョン13の翻訳が完了する検証し、リビジョン13の翻訳として採用する。
リビジョン12の翻訳が後から完了するリビジョン13の採用済みテキストを置き換えずに、リビジョン12の処理結果を記録として保持する。

翻訳を有効にする時点で、作業レコードに記録された原文のリビジョンを、現在の原文と比較します。比較から書き込みまでの間に別の編集が入っても見逃さないよう、ストレージシステムでは、そのリビジョンとの一致を条件に書き込みを行います。現在のリビジョンの処理がキューに追加されていない場合や失敗した場合は、古い結果を現在のリビジョンのものとして扱い直すのではなく、現在のリビジョンの処理をスケジュールします。

読み取り時には、要求された言語とリビジョンに対応する採用済み翻訳を取得します。翻訳がない場合の動作も決めておきます。原文を表示する、指定した代替言語を使う、明示的に追跡管理している古い翻訳を配信する、公開を保留するといった選択肢があります。どれが適切かは、古いテキストや未翻訳のテキストが読者に与える影響によって異なります。チェックアウト条件の変更には、気軽に読める商品説明よりも厳しい方針が必要になるかもしれません。

リモートの識別情報とローカルのレコードを使って復旧する #

送信前にリクエストの冪等性キーを永続化し、作成の応答が返ったらすぐにジョブIDを永続化します。ネットワークがタイムアウトした場合は、そのキーを使って内容を変えずに作成リクエストを再送するか、記録済みのジョブを取得します。開始操作を繰り返しても、処理対象は同じジョブです。

一時的な読み取りエラーが発生した場合は、バックオフを適用してポーリングします。クライアント側の待機期限に達しても、待機が終わるだけで、サーバー側の処理は停止しません。完了した翻訳先の出力と、失敗した翻訳先の詳細は別々に保持します。失敗したジョブにも、利用可能な完了済みファイルが含まれている場合があります。

認証エラー、無効化されたエンジン、不正な入力、アカウントの上限には、それぞれ対処が必要です。受付上限の問題が解消されれば、保留中のジョブを再び開始できます。実行中に失敗した処理については、原因を修正し、新しい冪等性キーを使って、該当するドキュメントとロケールを送信します。

採用時には、復旧後に取得した結果も含め、すべての結果に同じリビジョン確認を適用します。ダウンロードの完了が示すのは、テキストを利用できる状態になったことだけです。公開できるかどうかは、検証とレビューの方針に基づいて判断します。

レコードのライフサイクルをテストする #

変数を含む短いレコードを使い、原文の更新、特定ロケールでの失敗、翻訳が順不同で完了するケースを試します。文章だけでなく、保存されたフィールドのキーや言語の識別情報も確認します。アプリケーションは方針に沿って採用された版だけを配信し、レビュー担当者はその版から原文をたどれる必要があります。

品質測定に備え、原文と訳文の組を、評価に用いた基準とともに保持します。測定の設計は、生成ワークフローとは独立して適用できます。これにより、返されたテキスト、測定で得られた回答、人による採用、公開を一つのイベントとして扱わず、レコード上で区別できるようになります。