人によるレビュー API
レビュー待ちのドキュメントの翻訳先を検索し、レビュー権限を持つユーザーとして翻訳を承認したり、編集内容を送信したりできます。
レビューは、1つのドキュメントの1つの翻訳先言語を対象とします。設定した人によるレビューステージで、対象ユニットの判定準備が整うと利用できるようになります。ジョブを開始する前に、判定プールへのルーティングを設定してください。
レビューのリクエストには、組織へのアクセス権と、エンジンの翻訳をレビューする権限が必要です。判定リクエストには、さらに個人としての認証が必要です。レビュアーのセッションアクセストークンまたは個人用 API キーで認証してください。組織のサービスキーでは、人による判定を送信できません。
レビューを検索する #
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50レスポンスは { "data": [...], "meta": { "nextCursor": "..." } } です。nextCursor が null になるまでカーソルをたどってください。
| クエリフィールド | 値と既定値 |
|---|---|
statuses | open、completed、timedOut、cancelled。既定値は open です。複数の値を指定するには、同じパラメーターを繰り返し指定します。 |
order | oldest(既定値)または newest。 |
limit | 1~100。既定値は 50 です。 |
cursor | 前のページから取得した、内容を解釈せずに使用するカーソル。フィルターと並び順は変更しないでください。 |
判定済みのステータスを指定してリクエストするには、組織のレビューを管理する権限が必要です。各サマリーには、documentId、locale、jobId、engineId、engineName、documentKey、sourceLocale、provider、vendorStartedAt、status、readyAt、expiresAt、closedAt、totalUnits、pendingUnits が示されます。
レビューを1件取得する #
GET /v2/localization/documents/:documentId/targets/:locale/reviewレスポンスには、同じ翻訳先とエンジンのコンテキストに加え、units、引き継ぎ情報、記録済みの外部発注情報が含まれます。takeover は、人が引き継ぐまでは null です。発注が記録されていない場合、externalOrder は存在しないか、null になります。各ユニットには、unitId、key、position、source、value、reference、quality、eligibility、result、decision、reviewerId、decidedAt が含まれます。
原文の表示には sourceText を、編集を始める際の初期値には valueText を使用してください。判定後は settledText を表示します。これには承認された編集内容やその他の確定結果が含まれ、valueText にはレビュー前の翻訳が保持されます。結果が得られるまでは、settledText は valueText と同じです。
quality は、そのユニットに対する品質ゲートの出力で、パイプラインのリファレンスに記載されている { "findings": [...] }、またはゲートで確認されなかった場合は null になります。eligibility は required、qualityPassed、localeNotCovered、reused のいずれかです。人による判定が必要なのは、未判定の必須ユニットのみです。その他のユニットは、文脈を把握するための参考情報です。確定済みの result に値があっても、タイムアウトやフォールバックによる結果の可能性があります。人がユニットを承認または編集したかどうかは、decision で確認してください。
value は、レビューに入る時点の翻訳です。文字列、またはテキスト、変数、マークアップからなる構造化セグメントの配列です。編集時は、プレースホルダーの識別情報と入れ子構造を維持してください。
承認または編集する #
残りの必須ユニットをすべて、変更せずに承認します。
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-allこのリクエストに本文はありません。判定を明示的に指定するには、空でない配列に重複のないユニット識別子を指定して、/decisions に送信します。
{
"decisions": [
{ "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
{ "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
]
}取得したレビューに含まれる識別子を使用してください。構造化された値を編集するには、その valueText を基に編集し、編集後のテキストを Edited.value として送信します。たとえば、Hello {name}<C1>world</C1><C2/> を Bonjour {name}<C1>tout le monde</C1><C2/> に変更できます。プレースホルダートークンとその数、マークアップの入れ子構造は維持してください。同じ階層にあるプレースホルダーは移動できます。構造化テキスト内で文字として扱う区切り文字は、エンティティとしてエスケープされます。API はこのテキストを解析し、構造化セグメントに戻します。構造化セグメントの配列を直接送信することもできます。通常の文字列形式の ICU を編集する場合は、翻訳先言語に合わせたケースと個数を維持する必要があります。
リクエストが成功すると、更新後のレビューが返されます。内部レビュアーは、必須ユニットの一部だけを送信することもできます。判定は確定後に変更できません。翻訳先が判定を受け付けている間は、同じレビュアーが同じ内容を再送信すると、保存済みの判定が再利用されます。矛盾する判定は拒否されます。判定の書き込みは、送信内容全体の検証が完了してから行われます。
LocalizationReviewInvalid(422)は、プレースホルダーの変更など、送信内容が無効であることを示します。LocalizationReviewClosed(409)は、レビューまたはユニットがその判定を受け付けられなくなったことを意味します。翻訳先の処理完了後に再試行すると、最初の送信が成功していても 409 が返される場合があります。レスポンスを受信できなかった場合は、レビューを取得し、保存済みの判定とレビュアーの識別子を照合してから、残りの対応を判断してください。
外部レビューと引き継ぎ #
外部プロバイダーの現在の状態は GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status で確認してください。unstarted、inProgress、completed、unknown のいずれかです。
外部レビューを引き継ぐには、残りの必須ユニットすべての判定を1回のリクエストで送信する必要があります。これにより外部レビューが終了し、プロバイダーへの発注のキャンセルが試みられます。すでに開始された作業には、料金が発生する場合があります。状態の取得から判定の送信までの間にプロバイダーの状態が変わる可能性があるため、無料でのキャンセルは保証されません。
最終ファイルを待つ #
レビューの期限は、readyAt から算出される expiresAt です。ポーリングや再試行を行っても期限は延長されません。タイムアウト時は、未判定のユニットには警告が付き、直前の翻訳が保持されます。受け付け済みの判定はそのまま維持されます。
レビュー後も、後続のパイプラインステージでテキストが変更される場合があります。最終ファイルを入手するには、ジョブを取得し、完了した翻訳先をダウンロードしてください。レビューが完了しただけでは、ダウンロードする最終結果は得られません。