Anatomy of a localization execution layer: how a request flows from upload to native-speaker sign-off

Most engineering leads evaluating a localization vendor spend their diligence time on the wrong layer. They look at language coverage, turnaround claims, and pricing tiers, the things a procurement deck foregrounds, and treat the underlying system as a black box you throw files into and get translations back from. That works for a service relationship. For infrastructure you intend to call from a CI pipeline, a content platform, or an autonomous agent that fires off hundreds of requests a day without a human checking each one, you need more detail.

If localization is going to sit in your stack the way a payments processor or an auth provider does, you need to know its object model with the same rigor: what gets created, what state it has, how state transitions, what can fail mid-transition, and what you're responsible for handling on your side. This piece traces a single request through Ollang's execution layer, upload to order to quality check to sign-off, so you can reason about it before you build against it rather than after a retry storm teaches you the hard way.

Where the objects live

Ollang's API surface is organized around a small set of persistent objects: projects, orders, revisions, QC evaluations, and the webhooks that notify you when any of them change state. The platform exposes programmatic uploads, orders, projects, revisions, QC, human review, and webhooks, authenticated by API key. That object model, not a ticket queue or a project manager's inbox, is what you're actually integrating against. The full reference lives in Ollang's API documentation, and it's worth reading before you write a single request, the same way you'd read Stripe's object reference before wiring up billing.

There is also a hosted MCP-style access path for agent-driven invocation, but that is a distinct integration pattern with its own auth flow and is covered elsewhere. This piece stays inside the REST object lifecycle, since that determines how your systems handle state regardless of which client calls it.

The core flow: one request, five state transitions

Strip away the surface area and a single localization job moves through five concrete steps: create translation orders across formats like subtitles, closed captions, AI dubbing, studio dubbing, and document translation; manage orders by checking status, canceling, rerunning, and listing with filters; run QC evaluations for AI-powered quality checks; and handle revisions by creating, viewing, and deleting revision requests against a completed order.

Concretely, the lifecycle looks like this:

1. Upload → projectId. A file upload returns a projectId. Every downstream object, every order, every revision, hangs off this ID.
2. Order creation → orderId. Creating an order against that project returns one or more orderIds. A single project can spawn multiple orders, one per target language or one per output format, and each order is its own independently trackable unit.
3. Poll until completed. You monitor status by polling the order endpoint until it reports "completed." There is no long-lived streaming connection here, state is pulled not pushed unless you've registered a callback.
4. Run the quality check. A quality check against the completed order returns scores plus segment-level analysis. This is a distinct object from the order itself, an evaluation record with its own ID, not a field bolted onto the order.
5. Report issues via revision. If the QC scores or a human reviewer surface problems, you create revisions to report them. Optionally, the order can be upgraded to a professional linguist review at this stage.

That fifth step is the one engineering teams most often model wrong. A revision is not a support ticket bolted onto the vendor relationship, it is an addressable object with its own create, list, and delete operations scoped to a specific order. A revision can be created, listed, or deleted against a completed order, with delete operating on a specific revision ID within that order. That means your system can track exactly which linguistic issue was raised, when, and whether it was resolved or withdrawn, the kind of auditability a procurement-driven vendor relationship rarely gives you at the API level.

The QC evaluation itself is asynchronous and credit-metered. A QC run accepts criteria like accuracy, fluency, tone, and cultural fit, plus an optional custom prompt and callback URL, and returns an evalId with a credits-used count while processing continues in the background. Design your client to treat that response as a receipt, not a result, the real payload arrives via callback or a follow-up poll.

Querying and paginating the project graph

Once you're running localization at any real volume, "what's the state of everything" becomes as important as "what's the state of this one thing." Ollang's projects endpoint is built for that query pattern rather than requiring you to track every ID yourself. Retrieving all projects returns a paginated list associated with your account, and the endpoint supports query parameters for pagination, sorting, and searching.

In practice that means a request shaped like GET /integration/project?page=1&take=10&orderBy=createdAt&orderDirection=desc&search=video, authenticated with your API key in the request header. The pagination bounds are worth knowing before you architect a sync job: page size must be between 1 and 50, and the sort field accepts common values including id, name, createdAt, and sourceLanguage, with direction set to either ascending or descending. Sorting by sourceLanguage is how you filter or group by language pair programmatically, useful if your pipeline needs to reconcile every open Japanese-source project before a release freeze without paging through the entire account history to find them. Full parameter definitions are on the Retrieve All Projects reference.

Two routing models, one account

Here's a distinction that matters more than it looks on first read: Ollang supports routing configuration at two different levels, and which one governs a given order changes what "automatic" actually means. The account can be configured with global workflows or folder-level workflows, each with its own language-pair routing and provider selection.

A global workflow is your account-wide default, the AI provider and routing logic that applies when nothing more specific overrides it. A folder-level workflow lets you override that default for a subset of content: a specific product line, a specific client, a specific content type that needs a different provider or a stricter routing rule for a particular language pair. If your engineering team is building automation that creates orders inside specific folders, one folder per product surface for example, you need to know which workflow tier is actually deciding provider selection for that folder, because the account-level default and the folder-level override are not the same configuration surface and will not behave identically under the same API call.

The QC threshold gotcha: top-level orders only

This is the detail that catches teams building nested or workflow-spawned order structures, and it is the kind of thing you want to know before you ship an integration rather than after a threshold silently fails to fire. Automatic QC only applies to top-level orders, orders created directly, not to child orders generated as part of a parent workflow, and it also requires an account-level setting to be enabled.

Read that twice if you're planning to rely on automatic quality gating inside a multi-step pipeline. If your integration creates a parent order that itself spawns child orders, a common pattern in multi-language batch jobs, the automatic QC threshold you configured will fire on the parent but not automatically cascade to every child order underneath it. If your quality bar depends on every language variant getting evaluated, you either need to trigger QC evaluations explicitly on each child order or design your workflow so the orders you want gated are created as top-level orders in the first place. This is documented on the troubleshooting reference, and it is worth a re-read alongside your own workflow diagram before you assume threshold coverage is uniform across an order tree.

Timeouts, retries, and the realities of large assets

The last piece of the architecture a Head of Engineering needs before going to production is the operational envelope, what's slow, what fails silently, and what your client needs to tolerate.

Large uploads and format conversions are not instant, and treating them as if they should be is the most common source of false-negative failures in early integrations. Some operations, large uploads and format conversions, intentionally take minutes, so client HTTP timeouts should be increased to five to ten minutes for uploads, and connections should not be reused across unrelated requests. Certain conversion paths carry their own explicit ceiling: .ZIP uploads for motion-graphics conversion run through a retry-with-backoff path and carry a five-minute conversion timeout. If your upload client has a default 30-second timeout inherited from a generic HTTP wrapper, it will fail jobs that are actually succeeding on Ollang's side, a classic false negative that leads teams to build unnecessary retry logic on top of a request that was never actually broken.

Callbacks have their own contract and it is a tight one. The callback request has a 10-second timeout, if your server does not respond within 10 seconds the request is considered failed. That means your webhook handler needs to acknowledge immediately and process asynchronously, not perform the actual downstream work, publishing to a CMS, notifying a reviewer, or updating a status page inside the callback handler itself. And because callbacks are a best-effort notification layer, not a system of record, callback failures do not affect the order itself, and you should fall back to polling Get Order by ID if you do not receive a callback within a reasonable window. Treat every callback as a hint to check the authoritative state, not the state itself, do not rely on the body alone, pair the callback with a GET order confirmation using your API key before acting on the contents. Build your handlers idempotently too, use the orderId plus completedAt as a dedup key, or upsert into your store keyed by orderId, since redelivery is a normal part of any webhook system.

Why this matters more than the feature list

None of this is exotic. It's the same discipline you'd apply to any object-modeled API you were about to depend on for production traffic: know the entities, know the state transitions, know where automation quietly stops, child orders under a parent workflow, know where your client needs slack, large-file timeouts and callback windows. What's different about applying that discipline to localization is that almost no vendor in this category exposes enough of the model to make the exercise possible. A translation management system built around human project managers does not need a documented QC-threshold inheritance rule because a person is reading every job anyway. An execution layer does, because the whole premise is that no person has to.

Treat localization as infrastructure rather than a service for this reason: it becomes something your engineering org can reason about, test, and build reliability guarantees on top of, projects that page and filter predictably, orders whose QC behavior depends on documented account settings rather than an account manager's memory, revisions that are addressable objects instead of email threads, and callbacks with contracts precise enough to build idempotent handlers against. Evaluate it the way you'd evaluate anything else you're wiring into a critical path: read the object model first, then decide if it holds up under your failure modes.