翻訳ジョブを取得する

ドキュメントの翻訳先を確認し、完了を待って、利用可能な出力をダウンロードします。

作成時に返されたidを使って、ジョブを取得します。

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

レスポンスには、すべてのドキュメントとその翻訳先ロケールの情報が含まれます。一部の翻訳先が実行中、または失敗した状態でも、完了済みの翻訳先が含まれることがあります。

ジョブのフィールド #

フィールド意味
id, organizationId, engineIdジョブの識別情報、ジョブを所有する組織、エンジン。
sourceLocale原文の言語。
triggerapi、cli、ci、連携機能などの作成元。
statusタグで識別されるジョブの状態。詳細は後述します。
createdAt, updatedAtISO形式のタイムスタンプ文字列。
createdBy作成者の情報。取得できない場合はnull。個人キーを使った場合は、そのキーのユーザーが作成者として記録されます。
documentsドキュメント、その形式とソースアドレス、翻訳先ごとの進捗。
uploads待機中は、不足している成果物のアドレスとアップロード用URL。ジョブ開始後は空になります。

ジョブの状態 #

status._tag対応
Pending不足している成果物をアップロードし、/startを呼び出します。
Running時間をおいて再度ポーリングします。翻訳先の各ステージで、処理中かレビュー待ちかを確認します。
Completed出力をダウンロードして確認します。受け入れの判断にあたっては、各ステージの警告も確認します。
Failedstatus.messageと翻訳先の失敗情報を確認します。完了済みの翻訳先は引き続き利用できます。
Cancelled処理は停止しています。各翻訳先を確認し、完了済みの出力があるかを調べます。

Completed、Failed、Cancelledはジョブの最終状態です。一部失敗とは、完了した翻訳先と失敗した翻訳先が混在する、失敗状態のジョブを指します。

ドキュメントと翻訳先のフィールド #

各ドキュメントには、id、key、format、source、previousSource、targetsが含まれます。リクエストでインラインのJSONを指定した場合でも、sourceは成果物のアドレスです。previousSourceがない場合、その値はnullになります。

各翻訳先には、次のフィールドが含まれます。

フィールド意味
locale翻訳先の言語。
previousTranslation前回の翻訳先成果物のアドレス、またはnull。
status_tagフィールドにPending、Completed、Failedのいずれかが入ります。
stages状態とユニット数を含むステージの進捗。

完了した翻訳先の状態にはartifactとdownloadUrlが、失敗した翻訳先の状態にはmessageが含まれます。次のレスポンスの抜粋は、完了した翻訳先の状態を示しています。

json
{
  "_tag": "Completed",
  "artifact": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "downloadUrl": "/v2/localization/jobs/lfr_example/artifacts/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

実際に返されたアドレスとURLを使用してください。URLはhttps://api.lingo.devを基準とする相対URLで、認証が必要です。公開の署名付きダウンロードリンクではありません。ダウンロードでは、ドキュメントの形式に応じたファイルのバイト列が返されます。

複数の翻訳先で同じ成果物を共有する場合があります。Appleの文字列カタログでは、リクエストされた言語が1つの.xcstringsファイルにまとめられます。ダウンロードしたファイルをそれぞれ独立した単一言語のカタログとして扱うのではなく、まとめられた出力を一度だけ保存し、その中のロケールごとのエントリを確認してください。

ポーリングして出力を収集する #

アプリケーション側で待機期限を設け、2秒ごとなど、一定の間隔でジョブをポーリングします。取得が一時的に失敗した場合は、識別子を保持し、再試行の間隔を徐々に延ばしてください。待機を終了しても、サーバー側の処理はキャンセルされません。人によるレビューには、アプリケーションの短いリクエストタイムアウトを大幅に超える時間がかかる場合があります。

翻訳先の状態がCompletedになったら、その出力をダウンロードします。アプリケーションですべての言語を同時に公開する必要がある場合は、必要な翻訳先がすべて完了するまで待ち、アプリケーション側のストレージでその公開ルールを適用してください。1つのファイルが完了していても、すべてのロケールで成功したとは限りません。

ポーリングとダウンロードを行うプログラムの全体例は、クイックスタートを参照してください。原文のリビジョンの扱いと再試行の判断については、翻訳ワークフローを構築するを参照してください。