Your content changes, and now it has to reach every locale you ship in. A training module gets a new lesson. A CMS entry is saved. A product description is edited. The translation should fan out to German, French, Japanese, and a dozen more – and your app should not block while it happens.
The async localization API is built for exactly that moment: one request, every locale, results as they land. You POST your content once with the target locales, get a 202 back immediately, and the platform translates each locale as an independent background job. You keep your glossary, brand voice, and model configuration – the same engine the synchronous API uses – and you stop owning the retries.
On this page
The problem#
Training platforms, content management systems, and e-learning tools often need to translate content into dozens of languages the moment it is created or updated. The synchronous localization API works, but it forces a tradeoff at scale.
Take a training module authored in English that needs to reach learners in 14 languages. With the synchronous API you have two options, and both cost you something:
Fire 14 parallel calls – one request per target locale, each carrying the same source payload. You can render each language as it returns, but you are managing 14 network round-trips with redundant data, and you own the retry logic when one of them fails.
Translate all 14 in one synchronous call – fewer round-trips, but now you wait for the slowest locale before you can display any of them.
Either way, your application is tied up while translations process. If your server restarts mid-flight, the in-progress translations are gone. If one language fails, partial-failure handling is on you. And neither path gives your users a clean signal that translations are underway.
The async API removes the tradeoff. One request creates a job group with one job per target locale. Each job runs independently through your localization engine as a durable background workflow – so a server restart on your side loses nothing, because the work is not running in your process. Results are delivered per-locale the moment each one finishes. Your app stays responsive. Failures stay isolated. The platform owns the retries and the delivery.
One locale, and you can wait a second? Use sync.
The async API earns its keep when you have many locales, long content, or a UI that should show progress. If you need a single locale pair and can wait for one round-trip, the synchronous Localize endpoint is the simpler call – one request, translated data back in the response, no webhook endpoint to run. Reach for async when the job is too big, too slow, or too many-locale to block on.
How it works#
Three steps, and only the first one happens in your request/response cycle. The other two happen on the platform, on their own time.
Submit one request
POST your content and target locales to /jobs/localization. The API validates the payload, creates a job group with one job per locale, and returns 202 with the group ID and a job summary. Your application is free to continue immediately – nothing translates inside this call. See Create jobs for the full request and response shape.
The platform processes each locale independently
Each job runs through your localization engine via a durable background workflow, applying the same model selection, glossary, brand voice, and instructions as the synchronous API. Each job can optionally run through a pipeline of pre-edit, human review, post-edit, rephrase, and back-translation stages. A job moves from queued to processing to a terminal state: completed, completed_with_warnings, or failed – and one locale's outcome never blocks another's.
Receive results as each one lands
The moment a locale finishes, the platform delivers its result to your webhook URL. For live progress in your UI – a "3 of 14 ready" counter that updates as jobs complete – connect to the group's WebSocket. If you would rather pull, poll the group on an interval.
Authentication
Every request – REST and WebSocket – authenticates with your X-API-Key header. Keys are organization-scoped and reach every engine in the org. See Authentication for the details, and API Keys to create one.
The job group model#
One submission produces one group holding one job per target locale. That shape is the whole mental model, and it is what makes the hard questions answerable.
A skeptical reader is already running the list: what happens when a locale fails, and what happens to my app while all this is in flight? The group model answers both.
- Failures are isolated, because each locale is its own job. If German succeeds and Japanese fails, the German translation is delivered normally and the Japanese job carries its own
errorMessage. The group reportspartial, and the work that succeeded still ships. A failure in one locale cannot roll back another that already completed. The full status semantics live on Track a job group. - In-flight work survives a restart, because it does not run in your process. Each job is a durable background workflow on the platform. If your server reboots, nothing in progress is lost – you reconnect or poll, and the group is exactly where you left it.
- The group is a progress model you can wire to a UI. Store the
groupIdfrom the202, then drive a progress indicator from webhook deliveries or WebSocket snapshots. "3 of 14 languages ready" is a counter over the group's child jobs.
The honest cost of this model: you take on a small amount of integration the synchronous call does not ask for. To receive results you run an HTTPS webhook endpoint, or hold a server-side WebSocket, and you handle each locale as it arrives rather than reading translated data straight out of one response. In exchange, the platform owns the retries, the failure isolation, and the delivery – and your app never blocks on a translation.
That is the trade the async API is built to make: one request, every locale, results as they land. The next pages are the verbs of that sentence.
