Translation jobs

Create and start jobs containing one or more documents and target languages.

A job translates documents through one localization engine. Each document has a stable key and one target per requested language. Use inline JSON for in-memory content or artifact addresses for files.

All routes below use https://api.lingo.dev and API authentication.

Create a job #

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" } }
    }
  ]
}

Request fields #

FieldRequiredMeaning
engineIdYesEngine in the organization that the caller can translate with.
sourceLocaleYesSource language.
targetLocalesYesNonempty array of unique target locales. A document cannot target its own source locale.
documentsYesNonempty array of documents with unique key values.
originIdNoNonempty identity, up to 512 characters, for where the documents live; for example github:acme/web. It connects later edits from that origin to translation measurement.

Each document has:

FieldRequiredMeaning
keyYesNonempty logical file path or name, unique within this job. Keep it stable between revisions.
formatYesFormat object with a type and format-specific options.
sourceYesSHA-256 artifact address, or { "content": { ... } } for inline JSON.
previousSourceNoPrevious source artifact address. Omit or use null for a first translation.
previousTranslationsNoArray of { "locale": "de", "artifact": "SHA256" }. Defaults to []; each locale must be unique and belong to this document's targets.
targetLocalesNoNonempty, unique locale override for this document. Omission or null uses the job's target locales.

When using keyScope or termScope, supply a previous translation for every target. See document formats and updates.

Idempotency #

Send a nonempty Idempotency-Key of at most 255 characters. Keys are scoped to the engine; the content-sync: prefix is reserved. Retain the key with the original request and repeat that request unchanged after an uncertain create response.

A reused key returns the job originally created under it. It does not update that job's documents or locales. Use a new key for changed work. A conflicting run option can produce LocalizationJobIdempotencyKeyReused (422).

Create response #

A successful create returns HTTP 200 and the job response, normally with status: { "_tag": "Pending" }. Persist id before continuing. The uploads array lists missing input artifacts as { "address": "...", "uploadUrl": "..." }.

Creation stores inline sources. It does not start translation, even when uploads is empty.

Upload and start #

Upload each missing artifact to its uploadUrl with an authenticated PUT containing the original bytes. Then call:

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

The start request has no body. Its HTTP 200 response is the current job record. Repeating start is safe for the same job and can recover an uncertain dispatch; it does not create another job or rerun a finished one.

Start checks uploaded artifacts, engine configuration, and account limits. ArtifactsNotUploaded (409) lists missing inputs. A daily token limit (429) or insufficient credits leaves the job pending; correct the condition before starting it again. See errors.

Configure pipeline stages #

Configure the engine's pipeline before starting. Its configuration is captured at start. The job's resulting target stages show the work actually selected after plan availability is applied.

Collect results and recover #

Retrieve the job to inspect each target and download completed files. Use stage progress to distinguish model work, review waits, skipped work, and failures.

A failed job can still contain completed targets. Keep those outputs and submit only the work that needs regeneration with a new idempotency key after correcting the cause. Keep source revisions with job IDs so later delivery does not overwrite newer translations.

List jobs to find submissions by engine, state, trigger, or service key.