Inside the execution layer: an architecture explainer of orders, levels, and review gates

The problem with treating localization as a black box

Most engineering teams inherit localization the way they inherit a legacy billing system: a dashboard someone else logs into, a vendor contact who "handles it," and a process that produces files but exposes no state. You can't query it. You can't hook a webhook to it. You can't reason about it as a system with defined objects, transitions, and failure modes, the way you reason about your order-processing pipeline or your CI system.

That's the actual gap an execution layer has to close, and it isn't a UI problem. A polished dashboard sitting on top of an opaque backend does not make localization callable. What makes it callable is the object model underneath: a defined hierarchy of Folder, Project, Order, Level, Workflow, and Review Gate objects that are addressable, stateful, and observable through an API instead of a support ticket. This document walks through that model directly, because once you understand it, you can reason about localization the same way you reason about any other subsystem your team owns.

The object hierarchy: Folder → Project → Order

Ollang's structure starts with three nested containers. A Folder organizes related projects, think of it as the top-level namespace for a product line, a brand, or a business unit. A Project sits inside a Folder and groups the assets and settings for a given localization effort. An Order is the actual unit of work: a specific source asset, or set of assets, submitted for translation into one or more target languages.

This isn't incidental structure, the documentation frames the Folder → Project → Order hierarchy as the operational model you need to understand before integrating at all. The API reflects this directly: you can list and search folders to organize projects, list all projects or retrieve details for a specific project by ID, and list and search Ollang folders for organizing projects. That is addressable resource structure rather than dashboard convenience, the same pattern you'd expect from any REST-modeled system with parent-child scoping.

Below Order, two more concepts do the real mechanical work, Level and Workflow. A Level determines how much human involvement an order requires, AI-only output versus output that passes through a review gate. A Workflow determines which models, language pairs, and providers actually execute the work. Both are configured per order, not added afterward, which is the detail that matters for engineering teams: quality tier and routing logic live inside the same object graph as the asset itself, not in a separate ticketing layer.

Orders are stateful, not fire-and-forget

Treat an Order the way you'd treat a job in a queue system: it has a lifecycle, and that lifecycle is inspectable. An order stuck in pending or ongoing for a long time is expected in some cases, most AI orders complete within minutes, while Level 1 orders with human review depend on reviewer availability and may take hours. That state progression, uploaded, processing, in review, QC-scored, delivered, is queryable via a GET on the order resource, and it is also pushable via callback.

The callback contract is explicit about its own limits, which is useful for a vendor API. 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. Critically, 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. This is a deliberate design choice: the webhook is a convenience notification, the order resource itself is the source of truth.

The documentation also pushes you toward correct distributed-systems hygiene rather than assuming you'll get it right by accident. Treat callback handlers as idempotent, using the orderId plus completedAt as a dedup key, or upserting into your store keyed by orderId. It explicitly warns against trusting the payload alone. Do not rely on the body alone; pair the callback with a GET confirmation using your API key before acting on the contents. The full contract, including polling behavior, retries, pagination, and error handling, is documented in Ollang's API documentation.

A practical order lifecycle, as it plays out through the API or an agent, looks like this: upload a file to get a projectId, create an order to get an orderId, poll status until it reads "completed," run a quality check for scores and segment analysis, create revisions to report any issues, and optionally upgrade to a professional linguist review. Every one of those steps is a state transition on an object your systems can hold a reference to.

The Level 1 review gate: routing output to humans without leaving the object model

This is where the architecture earns its keep for enterprises that already have translation relationships they do not want to abandon. You can add a Level 1 review gate to any order to route output to Ollang-managed linguists or your own LSPs and editors. The gate does not fork you into a separate system. It is a property of the same Order object, which means the state machine, the QC scoring, and the webhook notifications all keep working identically whether the reviewer is an Ollang-managed linguist or your own vendor's editor logged in under an enterprise LSP role.

That review gate produces measurable output, beyond a "reviewed" checkbox. AI QC runs across accuracy, fluency, tone, and cultural fit, alongside human QC annotations, QC score progression, and human-edit-percentage analytics. Quality control is an object you can invoke on demand: you can run a standalone AI-powered QC evaluation on an order to assess translation quality across accuracy, fluency, tone, and cultural fit, though the order must be in a completed or delivered state to be eligible for evaluation. Full parameters and response fields are in the Run QC Evaluation reference.

If output does not clear the bar, act on the same order. You can create, list, or delete revision requests on a completed order to flag specific problems, or request a professional linguist review that upgrades AI-generated output with expert review. You can also rerun a completed order to regenerate the translation using the latest AI models if a model upgrade lands after your first pass. Each of these is a discrete API call against an existing object ID, not a new project, not a re-upload, not a new vendor conversation.

There is a governance detail worth knowing for anyone building automated QC gates into a pipeline: automatic QC only applies to top-level orders created directly, not child orders generated as part of a parent workflow, and it also requires enableQCThreshold on the client account. This is the kind of constraint you want documented plainly rather than discovered in production.

BYOK and multi-model routing live in the same object, not a side panel

The temptation for most vendors is to treat "bring your own model" or "choose your provider" as an account-level setting disconnected from the actual work objects. Ollang's documentation places BYOK inside the same conceptual model as folders, orders, and review gates. Folders, projects, orders, levels, workflows, review gates, LSPs, QC, and BYOK are documented together as the operating model, not as separate systems bolted side by side.

That matters because model and provider selection happen at the Workflow layer, which is scoped per order the same way a review gate is. The documentation describes global versus folder-level workflows, language-pair routing, and provider selection as configurable dimensions, meaning an enterprise can route Japanese legal documents through one model tier and marketing copy through another, without leaving the object hierarchy or standing up a separate routing layer. The underlying catalog spans multiple providers: Gemini tiers serve Document Translation, Subtitle Translation, and AI Dubbing within Ollang Workflows, while GPT-5-class and o-series models are positioned for complex, long-form, or reasoning-heavy translation and localization workflows. Provider and key configuration sit next to Level and Review Gate configuration in the API documentation, forming one object graph rather than a vendor abstraction layered on top of another.

Why the architecture, not the UI, is what makes this callable

A dashboard is a rendering of state. The reason Ollang can be invoked by pipelines, cron jobs, and AI agents instead of only by a human clicking through screens is that every meaningful action, such as upload, create order, apply a Level, add a Review Gate, run QC, request revision, corresponds to an addressable API operation on a well-defined object, authenticated by API key, documented with request and response shapes. This is what a Node.js SDK, a set of file-based Agent Skills, or a hosted MCP server actually plug into. The platform is API-key authenticated and exposes a hosted Model Context Protocol server using OAuth 2.0 with PKCE, both sitting on top of the identical order graph described above.

An agent running inside Claude or Cursor is calling the same Order and Level objects your backend would call, which is why an agent can upload files, create orders, run QC, and manage projects from a single conversation without a human ever opening the dashboard. Implementation details for each access path, REST, MCP, SDK, and Skills, are laid out in the docs.

This is the structural argument for treating localization as infrastructure rather than a service line. The object model is what survives contact with automation. A vendor relationship built on email threads and file drops has no equivalent of an Order ID, no Level property, no Review Gate you can toggle programmatically, and no QC score you can poll. Ollang's bet is that enterprises increasingly need a data model stable enough that engineering, procurement, and AI agents can all reason about the same objects, in the same states, through the same API surface, rather than only a nicer portal.