Read a translation job
Inspect document targets, wait for completion, and download available outputs.
Read a job using the id returned by creation:
GET /v2/localization/jobs/:id
X-API-Key: YOUR_API_KEYThe response describes all documents and their target locales. It can contain completed targets while other targets are still running or have failed.
Job fields #
| Field | Meaning |
|---|---|
id, organizationId, engineId | Job identity and owning organization and engine. |
sourceLocale | Source language. |
trigger | Origin such as api, cli, ci, or an integration. |
status | Tagged job state, described below. |
createdAt, updatedAt | ISO timestamp strings. |
createdBy | Creator information, or null when unavailable. A personal key is attributed to its user. |
documents | Documents, their formats and source addresses, and target progress. |
uploads | Missing artifact addresses and upload URLs while pending; empty after the job has started. |
Job states #
status._tag | What to do |
|---|---|
Pending | Upload missing artifacts and call /start. |
Running | Poll again later; inspect target stages for work or a review wait. |
Completed | Download and inspect the outputs. Check stage warnings as part of acceptance. |
Failed | Read status.message and target failures. Completed targets remain available. |
Cancelled | Work has stopped. Inspect targets for any outputs already completed. |
Completed, Failed, and Cancelled are terminal job states. A partial failure is a failed job with a mixture of completed and failed targets.
Document and target fields #
Each document contains id, key, format, source, previousSource, and targets. source is an artifact address even when the request supplied inline JSON. previousSource is null when absent.
Each target contains:
| Field | Meaning |
|---|---|
locale | Target language. |
previousTranslation | Previous target artifact address, or null. |
status | Pending, Completed, or Failed in its _tag field. |
stages | Stage progress, including status and unit counts. |
A completed target's status contains artifact and downloadUrl; a failed target's status contains message. This response excerpt shows a completed target status:
{
"_tag": "Completed",
"artifact": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"downloadUrl": "/v2/localization/jobs/lfr_example/artifacts/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}Use the actual returned address and URL. The URL is relative to https://api.lingo.dev and requires authentication; it is not a public signed download link. The download returns file bytes in the document's format.
Several targets can share an artifact. An Apple String Catalog combines the requested languages in one .xcstrings file; save that combined output once and inspect its locale entries rather than treating each download as a separate single-language catalog.
Poll and collect #
Poll the job with a bounded interval, such as two seconds, and an application deadline. On a temporary read failure, retain the ID and retry the read with backoff. Ending the wait does not cancel server processing. Human review can take substantially longer than a short application request timeout.
Download a target once its status is Completed. If your application needs all languages published together, wait for all required targets and apply that publication rule in your own storage. A single completed file is not evidence that every locale succeeded.
For a complete polling and download program, use the quickstart. For source-revision handling and retry decisions, see build a translation workflow.