翻訳ジョブ

1つ以上のドキュメントと翻訳先言語を指定して、ジョブを作成・開始します。

ジョブは、1つのローカライゼーションエンジンでドキュメントを翻訳します。各ドキュメントには固定のキーがあり、指定した言語ごとに1つの翻訳先が設定されます。メモリ内のコンテンツにはインラインのJSONを、ファイルにはアーティファクトのアドレスを使用します。

以下のすべてのルートでは、https://api.lingo.devとAPI認証を使用します。

ジョブを作成する #

http
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr
json
{
  "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を使用します。その後、次を呼び出します。

http
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEY

開始リクエストに本文はありません。HTTP 200のレスポンスとして、現在のジョブレコードが返されます。同じジョブに対して開始リクエストを繰り返しても安全で、実行依頼の結果が不確かな場合の復旧にも使用できます。別のジョブが作成されたり、完了済みのジョブが再実行されたりすることはありません。

開始時には、アップロードされたアーティファクト、エンジンの設定、アカウントの利用上限が確認されます。ArtifactsNotUploaded(409)には、不足している入力が列挙されます。1日あたりのトークン上限(429)に達した場合やクレジットが不足している場合、ジョブは保留のままになります。問題を解消してから、もう一度開始してください。詳しくは、エラーを参照してください。

パイプラインのステージを設定する #

開始前に、エンジンのパイプラインを設定してください。開始時点の設定が保存されます。ジョブの翻訳先ステージには、プランでの利用可否を反映したうえで、実際に選択された処理が表示されます。

結果を取得して復旧する #

ジョブを取得して各翻訳先を確認し、完了したファイルをダウンロードします。ステージの進行状況では、モデルによる処理、レビュー待ち、スキップされた処理、失敗を区別できます。

失敗したジョブにも、完了済みの翻訳先が含まれている場合があります。それらの出力は保存し、原因を解消してから、再生成が必要な処理だけを新しい冪等性キーで送信してください。後から届く結果で新しい翻訳が上書きされないように、翻訳元のリビジョンをジョブIDとともに保存してください。

ジョブ一覧を取得すると、エンジン、状態、トリガー、サービスキーで送信済みのジョブを検索できます。