A migration playbook: moving enterprise localization from ticket queues to an API-native pipeline

Every engineering team that inherits a localization workflow gets the same mess, a shared inbox, a spreadsheet of language pairs, a project manager who pings Slack when files land, and a release calendar that slips when someone forgets to CC the vendor. The failure mode is the request-and-wait model, which was built to be emailed by humans, not called by software.

The instinct, once engineering gets pulled in, is to treat this as a vendor swap: pick a new provider, get an API key, point the same manual process at a new endpoint, and declare victory. That's why most of these migrations stall six weeks in. Swapping vendors doesn't remove the ticket queue, it only gives the ticket queue an API key. The actual work is systems integration: ingestion, order orchestration, callback handling, state reconciliation, and revision logic, each with its own failure modes that only show up under production load.

This playbook treats the migration as what it is, a five-phase integration project you can plan sprints around, using the documented order lifecycle in Ollang's API documentation rather than a general "connect the API" mandate.

Where this sits in your stack

Ollang is an execution layer, not a portal your PMs log into. Ollang is an AI-native localization platform for video, audio, and document content. It orchestrates AI dubbing, subtitle translation, captions, transcription, document and visual translation, and human review workflows, and it provides access through APIs, an MCP server, an SDK, and agent Skills. For a head of engineering, the integration surface is a REST API you call from your own pipeline, for example a CI/CD job, a CMS publish hook, or a content-management event, not a UI your localization team operates by hand.

Authentication is API-key based. You obtain your API key from your Ollang dashboard, and it travels in a header on every request. That is the entire auth surface for the phases below, no OAuth dance or per-vendor portal logins to manage across teams.

Phase 1: Automate ingestion

The first sprint's job is narrow: replace "email the file to the vendor" with a programmatic upload that returns an identifier your system can act on. The documentation includes end-to-end walkthroughs for AI dubbing, subtitle pipelines, document localization, visual translation, audio description, and continuous i18n, and it provides production guidance on API keys, callbacks, retries, pagination, error handling, folder structure, and memory.

Uploads go through a direct file endpoint. The endpoint accepts a wide variety of file formats including video files (MP4, AVI, MOV, WMV), audio files (MP3, WAV, AAC, M4A), document files (DOCX, PDF, TXT, RTF), presentation files, and spreadsheet files, and uploaded files can be processed for translation into your target language. Subtitle-specific work has its own path, a VTT upload that accepts the subtitle file alongside an existing projectId to associate it with a prior video upload.

The output your pipeline needs to persist is the projectId. The upload step sends a source file to Ollang and returns a projectId used to create orders. Store that ID against your internal content record, such as a CMS entry, a repo commit, or a document version, because every subsequent order, rerun, and revision call depends on it.

Sprint deliverable: a service that accepts your internal content trigger, calls the upload endpoint, and writes projectId back to your system of record. No order logic yet. Make ingestion reliable before you touch orchestration.

Phase 2: Automate order creation

Once a projectId exists, the next step is to replace the "please translate this" email with a typed order request. The platform orchestrates AI dubbing, subtitle translation, captions, transcription, document and visual translation, and human review workflows, and these are reachable programmatically. The order-creation endpoint supports creating one or more translation orders for a project, including closed captions, subtitles, document translation, AI dubbing, and studio dubbing.

This is the phase where teams get sloppy if they skip mapping their internal request types to Ollang's order types first. Build a translation table, internal ticket category to Ollang order type, before writing the call. If your current ticket queue mixes UI string files, legal PDFs, and marketing video under one "localization request" label, that ambiguity has to get resolved in code, not left for a human dispatcher to interpret at submission time, because there is no longer a human dispatcher in the loop.

The order-creation call returns an orderId, or an array of them for multi-language batches. That ID, along with projectId, becomes the primary key for everything downstream, and status checks, QC runs, reruns, and revisions all key off it.

Phase 3: Build idempotent callback handlers

This is where most home-grown integrations break in production, and it is the phase engineering teams most consistently underestimate. When you supply a callback URL on order or QC creation, Ollang posts back to it on completion, but networks retry, and your handler will receive the same completion event more than once. The order lifecycle flow expects you to monitor status until it reaches "completed" and then run quality checks and handle revisions, and each of those steps needs to survive being triggered twice for the same event.

The documentation is explicit about this. Treat callback handlers as idempotent and use the orderId plus completedAt as a dedup key, or upsert into your store keyed by orderId. Build your handler as an upsert against orderId from day one, not as a bolt-on fix after you discover duplicate downstream actions, such as duplicate customer notifications, duplicate CMS publishes, or duplicate billing events in production.

Two more constraints shape the handler's design. Callbacks have a 10-second timeout, and if your handler takes longer to respond, Ollang treats it as a failure, so acknowledge quickly and process asynchronously. Your webhook receiver should validate, dedupe, enqueue, and return 200. Push the actual downstream work, publishing, notifying, re-indexing, onto a queue your handler does not block on.

Phase 4: Add a polling fallback

A pipeline that trusts webhooks exclusively has a silent failure mode: a dropped callback, a firewall misconfiguration, or a deploy that briefly took your endpoint offline. Callback failures do not affect the order itself, and the recommended fallback is to poll Get Order by ID if you do not receive a callback within a reasonable window.

Even when a webhook arrives, verify it with a GET confirmation against the order using your API key before acting on it. Pairing the callback with a confirmed read-back closes a real gap: a spoofed or malformed payload hitting your public endpoint should not be able to trigger a production action without a verified read-back from Ollang's state.

Practically, this phase means building two entry points into the same state-transition logic, one triggered by the webhook and one triggered by a scheduled poll (via Get Orders or Get Order by ID) that sweeps for orders stuck in a non-terminal state past an expected SLA. Both paths should converge on the same idempotent handler from Phase 3.

Phase 5: Instrument rerun and revision flows

The old ticket queue existed to handle exceptions: the mistranslation someone caught in QA, the subtitle timing that drifted after a re-edit, or the translation that needs regenerating because the source model or guidelines changed. Replacing the intake ticket without replacing this exception path moves the bottleneck; now someone has to email support instead of filing a ticket.

Ollang's documented lifecycle covers this. Reruns handle full regeneration, regenerating the translation using the latest AI models on a completed order, and the trigger can be as simple as a flagged QC score or a stale-content check in your own pipeline calling the rerun endpoint directly. Revisions handle targeted fixes, creating, listing, or deleting revision requests on a completed order to flag subtitle timing issues, mistranslations, or other problems.

Build both as first-class actions in your internal tooling, not manual escapes back to email. If your QA team currently flags an issue by filing a ticket, that same action should write a revision request against the orderId tied to the specific segment or timestamp. If your content pipeline detects that source content changed after an order completed, it should trigger a rerun automatically rather than waiting for someone to notice the translation is stale. When an AI-generated result needs professional sign-off, requesting a human review for an existing order triggers a manual review by a professional linguist.

Sequencing and the case for doing it this way

Each phase produces something independently useful and testable, and you can ship Phase 1 and still be manually creating orders in a dashboard while ingestion is proven out. That incremental approach lets you validate assumptions about file types, order-type mapping, and callback reliability before the whole pipeline depends on all five phases working together.

Teams that try to build all five at once tend to discover their callback handler was not idempotent only after a retry storm during a peak release cycle, or that they never built a polling fallback because the webhook worked fine in staging. Sequencing the migration as a real project, with the order lifecycle, callbacks, and rerun/revision endpoints as the concrete units of work, separates a team that ends up with resilient programmable localization infrastructure from one that ends up with a faster-looking ticket queue that has an API key. The distinction matters because the second outcome still fails the same way the old one did, quietly under load right before a launch.