Inside the localization execution plane: a systems architecture explainer

Every engineering leader who has tried to automate localization eventually hits the same wall: the vendor's dashboard makes sense to a project manager, but nobody can tell you what object survives a rerun, what triggers a re-route to human review, or what state a job is actually in when a webhook fires twice. You end up building your own state machine on top of someone else's black box, because the vendor never published the one that matters, the data model.

That's the wrong way to build automation on top of a localization system, and it's the reason most "AI localization" integrations rot within two quarters. An execution layer is only as reliable as the object model underneath it. If you can't reason about how a source asset moves from upload to delivery, what gets versioned, what gets gated, what gets scored, you can't build retries, rollbacks, or SLAs around it with any confidence.

This piece treats Ollang's object hierarchy like a systems design doc: folders, projects, orders, levels, workflows, review gates, LSPs, QC, and BYOK, as they're actually documented in Ollang's API reference.

The shape of the object model

Ollang's documentation organizes the platform around a small set of nouns that compose predictably. Ollang takes a source asset, a video, audio file, document, image, subtitle file, or strings file, and produces multilingual, fully reviewable localization outputs organized around folders, projects, and orders, with levels, workflows, review gates, QC, BYOK, and more attached. The docs frame the folder → project → order chain as conceptual groundwork you should understand before writing integration code, and the Project Management Dashboard documentation exists to help you understand the operational model before integrating.

That ordering is deliberate. Folders are the organizational scope, projects are the unit of uploaded content, and orders are the unit of work performed against that content. Everything else, levels, workflows, review gates, QC, BYOK, attaches to one of those three objects rather than existing independently.

Folder → project → order: tracing a source asset

At the top of the hierarchy sits the Folder, which groups projects for organizational and routing purposes. You can list and search them programmatically via a dedicated endpoint, GET /integration/folder, which retrieves all folders for organizing projects.

Below the Folder is the Project, created the moment a source file lands in the system. Upload is its own call, and the response is what everything downstream keys off. Uploading a source file to Ollang supports video, audio, documents, spreadsheets, and VTT subtitle files, and returns a projectId used to create orders. Projects carry metadata that matters for automation, including source language, folder association, and creation time, and can be queried individually or in bulk, filtered and sorted. The field to sort results by supports common values like id, name, createdAt, sourceLanguage, in ascending or descending direction, with search filtering by name or other searchable fields, case-insensitive and supporting partial matches.

The Order is where translation actually happens. One project can spawn multiple orders, for different target languages or modalities, and each order type maps to a distinct deliverable. An order creation call creates one or more translation orders for a project, supporting types including closed captions, subtitles, document translation, AI dubbing, and studio dubbing. The API is explicit that fan-out is per language: targetLanguageConfigs must be a non-empty array, and each entry creates a separate order, with language codes following the Supported Languages reference. That's an important architectural detail if you're building a pipeline that needs to track completion per language rather than per batch, you're tracking N orders, not one project-level status flag.

Order state is queryable at any point, and the response is rich enough to drive orchestration logic without a second API call. Retrieving full details of a specific order by ID includes status, languages, documents, and QC results. If you're building retry logic or SLA dashboards, this is the object to poll, the Get Order by ID reference documents which fields are available.

Levels: review requirements as an order attribute

Ollang treats how much human oversight an order needs as a first-class attribute rather than a separate product tier. Levels implement that: a Level 1 review gate can be added to any order to route output to Ollang-managed linguists or your own LSPs and editors. The distinction between AI-only and AI-plus-human is a state on the same Order object, which is why the docs describe it as configurable per order. AI-only versus AI plus human review governs the editor interface, assignments, and QC annotations attached to that order.

Operationally, this shows up in timing expectations you should build into your polling or timeout logic. Most AI orders complete within minutes, while level-1 orders with human review depend on reviewer availability and may take hours. An engineer wiring this into a CI/CD-style content pipeline needs to treat level-gated orders as long-running async jobs with a different SLA than pure-AI orders, not as a variant of the same fast path.

Workflows: the routing layer above individual orders

If levels answer whether an order gets reviewed, workflows answer which provider and routing logic executes it. Workflows sit above the order object and can be scoped globally or to a specific folder. Workflows govern global versus folder workflows, language-pair routing, and provider selection.

This mechanism lets an enterprise say, for example, "German legal content in this folder always routes through a specific provider configuration" without touching order-creation code for every request. The routing rule lives at the folder level, and every order created underneath it inherits that logic. It also explains a subtlety in how reruns behave. A rerun re-executes against the current workflow, and if the workflow, providers, custom instructions, and source content are unchanged, the AI may produce nearly identical output. Updating the relevant folder workflow or attaching guidelines before rerunning is what actually changes the result. For an engineer debugging why a rerun produced the same translation, the answer is architectural: reruns replay a workflow, so the workflow itself is the lever.

Custom guidance also attaches at this layer rather than the order layer. Translation memories, custom instructions, and folder- and project-level guidelines are configured once and inherited by every order that flows through that scope, which is the correct place for them architecturally, since you don't want a hundred orders each carrying redundant configuration.

Review gates: inserting linguists without rebuilding the pipeline

Review gates are the mechanism, while levels decide whether a gate exists. Review gates decide who sits behind it. The same completed order can be escalated after the fact: requesting a human review for an existing order triggers a manual review by a professional linguist, used when you want a professional to review the delivered content for quality assurance or compliance reasons. Escalation is reversible, which matters for cost control in automated pipelines. Review gates respect qcThreshold routing rules and orders may be re-routed automatically. Cancel Human Review reverts to the AI-only state and refunds review credits if priority changes.

That reversibility matters for engineers: a review gate is a state transition on an order object, not a fork into a separate workflow you have to reconcile later. Whether the linguist behind the gate is Ollang-managed or your enterprise LSP is a routing decision, not a different integration path, the same Request Human Review endpoint applies either way.

QC as a queryable object, not a PDF report

This is where many traditional TMS platforms differ: quality assessment is often an artifact you request once at project close, disconnected from the order state machine. Ollang models QC as its own callable object with a dedicated endpoint. Running a standalone AI-powered QC evaluation on an order assesses translation quality across criteria including accuracy, fluency, tone, and cultural fit. The call is explicit about which dimensions you're scoring and supports steering the evaluation itself:

POST /integration/orders/{orderId}/qc
{
"accuracy": true,
"fluency": true,
"tone": true,
"culturalFit": true,
"customPrompt": "Please focus on technical terminology accuracy",
"callbackUrl": "https://example.com/webhooks/qc-completed"
}

The response confirms the evaluation started, returns an evalId, reports credits used, and flags that it's still processing. That pattern tells you QC is asynchronous and webhook-driven, not a blocking call you should hold a connection open for. Segment-level granularity is part of the same response contract: the QC evaluation returns scores for accuracy, fluency, tone, and cultural fit, plus segment-level analysis.

Beyond the AI score, the model tracks human correction behavior as its own analytics surface. AI QC across those dimensions is paired with human QC annotations, QC score progression, and human-edit-percentage analytics. Edit-percentage is the metric worth building dashboards around, because it tells you per language pair or per folder workflow how much a human editor actually touched the AI output, which is a more direct quality signal than a static AI score. The Run QC Evaluation reference documents the full request and response shape.

BYOK: keeping model choice out of workflow logic

BYOK is easy to under-appreciate because it doesn't show up in the happy-path tutorial. Its role is architectural rather than functional: it keeps which model or provider executes the translation separate from what routing and review logic governs the order. Workflows already own provider selection at the routing layer, and BYOK lets that provider selection point at credentials the enterprise controls rather than credentials bundled into the platform.

For a head of engineering, the practical implication is this: swapping or adding a model provider shouldn't require touching order-creation code, review gate configuration, or QC thresholds. If model selection were baked into the order or workflow object directly, every provider change would ripple through every integration point that references it. Decoupling it into its own object means procurement, security, and model-selection decisions can move independently of the pipeline logic your team has already built and tested. Separating credential and model ownership from execution logic reduces blast radius when either one changes.

What changes operationally

None of this matters unless it's callable. Ollang's object model is exposed the same way regardless of whether the caller is a human dashboard user, a CI pipeline, or an agent: programmatic uploads, orders, projects, revisions, QC, human review, and webhooks are API-key authenticated. Agent-native access runs through a separate hosted surface built for that purpose: a hosted Model Context Protocol server, authenticated via OAuth 2.0 with PKCE, that integrates with hosts such as Claude, Cursor, Claude Code, Devin, Replit, and Windsurf. There is also a typed client and file-based agent packages for teams that want procedural rather than raw-HTTP integration: a TypeScript/Node.js SDK handles asset scanning, i18n workflows, CMS capture, and a typed REST client, while file-based Agent Skills for Cursor, Claude Code, Codex, and Windsurf provide natural-language ops with no server to run.

The operational shift versus a traditional vendor or TMS setup is structural, not cosmetic. In a project-based model, review and quality are steps a project manager schedules and reports back manually. Here, level, review gate, and QC are queryable states on an order your systems can poll, gate deployments on, or trigger remediation from, and workflow and BYOK let you change routing and provider logic without redeploying the integration that calls them. Rate limits, timeouts, and retry semantics are documented rather than discovered by trial and error. Ollang enforces per-account rate limits, back off exponentially on a 429, and some operations like large uploads intentionally take minutes, so HTTP client timeouts should be increased accordingly.

The argument, restated

Most localization vendors sell you a workflow and hide the data model behind it, which is fine until you need to automate around edge cases, partial failures, re-routing, quality regressions, provider changes, that the workflow UI was never built to expose. Ollang's approach is for engineering teams building automation to have a small, composable set of objects, folder, project, order, level, workflow, review gate, QC, BYOK, where every state transition is a documented API call, not a support ticket. The object model is the product, and everything else is a client of it. Before you build automation on top of any localization system, ask to see this diagram. If the vendor can't produce one, you're not integrating with infrastructure, you're scraping a dashboard.