Build a translation API workflow
Translate application records on the server and keep accepted language versions associated with the source revision they describe.
When an editor updates a product description, each translated version needs to reflect that change. An API response supplies the new text; your application decides which record it belongs to, whether the source is still current, and when readers can see it.
This guide extends a first translation request into a repeatable backend workflow. It fits records such as product descriptions and help entries that your application owns. Static application resources often fit a CI file workflow better, because resource compilation and repository review already provide a place to validate them.
Send a coherent piece of content #
Create a localization job with one inline JSON document for a product record. Group related fields so context can describe their purpose, and preserve stable keys so the downloaded object maps back to those fields.
Submit this body to POST /v2/organizations/:orgId/localization/jobs, with an API key and a stable Idempotency-Key for this revision:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "products/bottle.json",
"format": {
"type": "json",
"options": {
"context": "Product listing for a reusable drinks bottle",
"hints": {
"$.title": ["Catalog card title"],
"$.description": ["Short product description; do not add specifications"]
}
}
},
"source": {
"content": {
"title": "Insulated bottle",
"description": "Keeps drinks cold during your commute."
}
}
}
]
}Keep credentials in the backend and select the engine explicitly. Use shared glossary guidance for product terminology and document context for this particular use. The JSON reference covers hints and protected paths.
Run translation in background work #
Save the returned job ID before starting it. Upload anything listed in uploads, then call POST /v2/localization/jobs/:id/start. Even inline JSON needs this explicit start.
Poll the job from your backend worker and download completed targets using their returned URLs. The editor's save request can return once your application has durably queued this work. It does not need to stay open while translation or human review runs.
For incremental updates, retain previous source and accepted target artifacts and supply them in the next document request. Document updates explains the reuse boundary.
Record work after the source is saved #
After the source transaction commits, create a work record in your own storage with the content ID, source revision, target locale, localization engine/configuration record, and processing state. Queue translation from that record. This prevents a worker from translating an edit that the source transaction later rolls back.
Keep one outcome per target language. German may be ready while French needs retry or review. Recording only one overall “translated” flag would hide that difference from the application deciding what to serve. Any state names you add belong to your application's design, not to the API's response vocabulary.
Accept output only for the intended revision #
Source edits and translation completions can arrive in a different order. Consider this sequence:
| Event | Application action |
|---|---|
| Revision 12 is saved | Queue revision 12 for German. |
| Revision 13 is saved before that work finishes | Queue revision 13 and mark it as the current source. |
| Revision 13's translation finishes | Validate and accept it under revision 13. |
| Revision 12's translation finishes later | Retain its recorded outcome, without replacing revision 13's accepted text. |
Compare the work record's source revision with the current source at the point of activation. Make the comparison and write conditional on that revision in your storage system, so another source edit cannot occur unnoticed between them. If current work was not queued or failed, schedule the current revision rather than relabeling an older result.
At read time, ask for the accepted translation for the requested language and revision. Decide what the application does when it is missing: show source text, use a designated language fallback, serve an explicitly tracked older translation, or hold publication. The right choice depends on what stale or untranslated text could mean to the reader. A changed checkout condition may warrant a stricter policy than a casual product description.
Recover with the remote identity and local record #
Persist the submission's idempotency key before sending it and its job ID as soon as creation returns. After a network timeout, repeat the unchanged create request with that key or retrieve the recorded job. Repeating start operates on the same job.
Poll with backoff after temporary read failures. A client deadline stops waiting, not server work. Retain completed target outputs and failed target details separately; a failed job can still contain usable completed files.
Authentication errors, disabled engines, invalid input, and account limits need correction. A pending job can be started again after an admission limit is resolved. For work that has failed during execution, correct the cause and submit the affected documents/locales with a new idempotency key.
At acceptance, apply the same revision check to every result, including results retrieved after recovery. Download completion establishes that text is available; your validation and review policy decides whether it can be published.
Test the record lifecycle #
Use a short record with a variable, then exercise a source update, a failed locale, and completions arriving out of order. Inspect the stored field keys and language identities as well as the prose. The application should serve only the version your policy accepts, and a reviewer should be able to trace it back to its source.
For quality measurement, retain the paired source and target with the criterion used to examine them. Measurement design applies independently of the generation workflow. Your record can then distinguish returned text, a measurement answer, human acceptance, and publication instead of treating them as one event.