翻訳ジョブ
1つ以上のドキュメントと翻訳先言語を指定して、ジョブを作成・開始します。
ジョブは、1つのローカライゼーションエンジンでドキュメントを翻訳します。各ドキュメントには固定のキーがあり、指定した言語ごとに1つの翻訳先が設定されます。メモリ内のコンテンツにはインラインのJSONを、ファイルにはアーティファクトのアドレスを使用します。
以下のすべてのルートでは、https://api.lingo.devとAPI認証を使用します。
ジョブを作成する #
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "order-confirmation.json",
"format": { "type": "json" },
"source": { "content": { "subject": "Your order is confirmed" } }
}
]
}リクエストのフィールド #
| フィールド | 必須 | 説明 |
|---|---|---|
engineId | はい | 呼び出し元が翻訳に使用できる組織内のエンジン。 |
sourceLocale | はい | 翻訳元の言語。 |
targetLocales | はい | 重複のない翻訳先ロケールの配列。空にはできません。ドキュメントの翻訳元ロケールを、そのドキュメントの翻訳先に指定することはできません。 |
documents | はい | keyの値が重複しないドキュメントの配列。空にはできません。 |
originId | いいえ | ドキュメントの保存場所を示す、最大512文字の空でない識別子。例:github:acme/web。その保存場所で後から行われた編集を、翻訳の測定に関連付けます。 |
各ドキュメントには、次のフィールドがあります。
| フィールド | 必須 | 説明 |
|---|---|---|
key | はい | ジョブ内で一意の論理ファイルパスまたは名前。空にはできません。リビジョンが変わっても同じ値を維持してください。 |
format | はい | typeと形式固有のoptionsを持つ形式オブジェクト。 |
source | はい | SHA-256のアーティファクトアドレス。インラインのJSONの場合は{ "content": { ... } }。 |
previousSource | いいえ | 前回の翻訳元アーティファクトのアドレス。初回の翻訳では省略するか、nullを指定してください。 |
previousTranslations | いいえ | { "locale": "de", "artifact": "SHA256" }の配列。既定値は[]です。各ロケールは重複せず、このドキュメントの翻訳先に含まれている必要があります。 |
targetLocales | いいえ | このドキュメントの翻訳先を上書きするロケール指定。空にはできず、重複も認められません。省略するかnullを指定すると、ジョブの翻訳先ロケールが使用されます。 |
keyScopeまたはtermScopeを使用する場合は、すべての翻訳先について前回の翻訳を指定してください。詳しくは、ドキュメントの形式と更新を参照してください。
冪等性 #
最大255文字の空でないIdempotency-Keyを送信してください。キーの有効範囲はエンジン単位で、接頭辞content-sync:は予約済みです。キーを元のリクエストとともに保存し、作成リクエストへの応答が不確かな場合は、同じリクエストを変更せずに再送信してください。
キーを再利用すると、そのキーで最初に作成されたジョブが返されます。そのジョブのドキュメントやロケールは更新されません。処理内容を変更する場合は、新しいキーを使用してください。実行オプションが競合すると、LocalizationJobIdempotencyKeyReused(422)が返される場合があります。
作成時のレスポンス #
作成に成功すると、HTTP 200とジョブのレスポンスが返されます。通常はstatus: { "_tag": "Pending" }が含まれます。次に進む前に、idを永続的に保存してください。uploads配列には、不足している入力アーティファクトが{ "address": "...", "uploadUrl": "..." }として列挙されます。
作成時には、インラインの翻訳元データが保存されます。uploadsが空であっても、翻訳は開始されません。
アップロードして開始する #
不足している各アーティファクトを、それぞれのuploadUrlにアップロードしてください。その際は、元のバイト列を含む認証済みのPUTを使用します。その後、次を呼び出します。
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEY開始リクエストに本文はありません。HTTP 200のレスポンスとして、現在のジョブレコードが返されます。同じジョブに対して開始リクエストを繰り返しても安全で、実行依頼の結果が不確かな場合の復旧にも使用できます。別のジョブが作成されたり、完了済みのジョブが再実行されたりすることはありません。
開始時には、アップロードされたアーティファクト、エンジンの設定、アカウントの利用上限が確認されます。ArtifactsNotUploaded(409)には、不足している入力が列挙されます。1日あたりのトークン上限(429)に達した場合やクレジットが不足している場合、ジョブは保留のままになります。問題を解消してから、もう一度開始してください。詳しくは、エラーを参照してください。
パイプラインのステージを設定する #
開始前に、エンジンのパイプラインを設定してください。開始時点の設定が保存されます。ジョブの翻訳先ステージには、プランでの利用可否を反映したうえで、実際に選択された処理が表示されます。
結果を取得して復旧する #
ジョブを取得して各翻訳先を確認し、完了したファイルをダウンロードします。ステージの進行状況では、モデルによる処理、レビュー待ち、スキップされた処理、失敗を区別できます。
失敗したジョブにも、完了済みの翻訳先が含まれている場合があります。それらの出力は保存し、原因を解消してから、再生成が必要な処理だけを新しい冪等性キーで送信してください。後から届く結果で新しい翻訳が上書きされないように、翻訳元のリビジョンをジョブIDとともに保存してください。
ジョブ一覧を取得すると、エンジン、状態、トリガー、サービスキーで送信済みのジョブを検索できます。