Inside the localization data model: folders, projects, orders, levels, and review gates

Every engineering team that integrates localization eventually asks the same question, usually after the first production incident: what actually happens between "submit this content" and "get translated content back," and how much of that path can we control programmatically? Vendor sales decks answer this with buzzwords. They don't answer it with a data model. Without a data model, you can't design a pipeline, you can only design a workaround.

The argument here is narrow and practical: the way a localization platform structures its core objects, folders, projects, orders, review levels, tells you immediately whether it was built to be called by systems or requested by people. A platform built around tickets and project managers will have a data model that reflects that: loosely typed statuses, review steps buried in UI workflows, no queryable audit trail. A platform built as infrastructure will expose a hierarchy that maps cleanly onto how engineering teams already think about work: a namespace, a unit of content, a unit of execution, and a gate that can be opened or closed without touching anything upstream.

Ollang's documentation frames this explicitly. Conceptual documentation for the Ollang Project Management Dashboard covers the Folder → Project → Order hierarchy and why it matters, and the broader concepts reference spans Folders, Projects, Orders, Levels, Workflows, Review Gates, LSPs, QC, BYOK, and more. Read that documentation before you write a single line of integration code, because it determines how your pipeline will shard work, retry failures, and report status back to whatever system is asking for it, your CMS, your CI job, or an agent acting on your behalf.

The hierarchy as the operational backbone

Three objects do the structural work.

Folder is the namespace. It is how you organize projects for a product line, a market rollout, or a client account, the container that keeps a thousand orders from becoming an unsearchable flat list. Every project carries a folder reference for this reason: the Retrieve All Projects response includes an identifier of the folder associated with the project for organization purposes.

Project is the unit of content, the source asset and its metadata, independent of what you do with it. You upload once, then execute against it repeatedly. The upload endpoint is intentionally source-agnostic: it supports video, audio, documents, spreadsheets, and VTT subtitle files, and it returns a projectId used to create orders. That separation matters for pipeline design, a single project can spawn multiple orders (different languages, different modalities, different review depth) without re-uploading the source every time.

Order is the unit of execution, a specific translation job against a project, with its own type, target languages, and status. Order creation creates one or more translation orders for a project, supporting order types including closed captions, subtitles, document translation, AI dubbing, and studio dubbing. Each project also tracks the number of orders related to it, though that field may not be present in all responses, a small detail, but it tells you the object model treats order count as derived data rather than something you have to compute client-side.

This three-layer structure is the backbone the rest of the system hangs off. It is documented as platform concepts rather than UI screens. The vendor expects you to reason about it as a schema rather than a workflow you click through. Full field-level detail is in Ollang's API documentation.

Level 1 review gates: routing without reshaping the pipeline

The part of this model that matters most to an engineering lead is the review gate, because it is the one decision point where "AI-only" and "human-reviewed" content diverge, and in most platforms that divergence means rebuilding your integration. Ollang treats it as a flag on the existing order object rather than a fork in the pipeline: you can add a Level 1 review gate to any order to route output to Ollang-managed linguists or your own LSPs and editors.

Practically, this means the shape of your pipeline call doesn't change based on quality tier. Whether an order resolves purely through AI translation or gets routed to a linguist, Ollang's own managed pool or an LSP relationship you already have, is a routing decision made at the order level, not an architectural one made at the integration level. That is the difference between needing a separate system for human-reviewed content and flipping a parameter.

The human review path is its own endpoint, callable independently after the fact: Request Human Review for an Order triggers a manual review by a professional linguist, and eligibility is scoped, the order should be a completed or delivered order that you have access to and is eligible for human review. It returns no content on successful request (HTTP 204 status code), which is an implementation detail if you're writing client code that expects a payload back, you're not polling this call for a result, you're polling the order itself.

The upgrade path can also be reversed, a cancel-human-review endpoint exists for orders that were routed to review but no longer need it, which matters if your pipeline auto-escalates based on a QC score and needs to walk that decision back.

QC scoring, human-edit-percentage, and revision data as queryable objects

This is where the data model either earns its keep as infrastructure or reveals itself as a project-management tool with an API bolted on. Quality data needs to be queryable, not just visible in a dashboard, if it's going to feed automated gating logic, auto-approve above a threshold, auto-escalate below it, or flag drift in a specific language pair over time.

Ollang attaches QC as structured data on the order: AI QC across accuracy, fluency, tone, and cultural fit; human QC annotations; QC score progression and human-edit-percentage analytics. The Run QC Evaluation endpoint lets you specify exactly which dimensions to score, the request body accepts flags for accuracy, fluency, tone, and culturalFit, plus a customPrompt field, which means you can build QC criteria specific to a content type, marketing copy weighted toward tone, technical documentation weighted toward accuracy, rather than accepting one generic score.

Revisions are handled the same way, as records attached to an order, not as support tickets. The revision endpoints let you create, list, or delete revision requests on a completed order, and you'd use this to flag subtitle timing issues, mistranslations, or other problems. That means revision history is something your team can query and report on, not something buried in an email thread with a project manager.

For an engineering team, the operational implication is straightforward: QC scores, human-edit percentages, and revision counts become metrics you can pull into your own dashboards and alerting, not numbers you have to request from an account manager.

Webhook design, callbacks, and why polling vs. async matters

Localization jobs are not instant. Dubbing a video or running a document through human review takes real time, and any pipeline that treats a translation call like a synchronous REST request will either time out or block a worker for no reason. This is the exact design tension addressed in Ollang's production guidance, which covers API keys, callbacks, retries, pagination, error handling, folder structure, and memory in the production reference documentation.

Two patterns exist side by side, and picking the right one for each stage of your pipeline is a design decision, not a default. QC evaluation demonstrates both directly: the endpoint accepts a callbackUrl in the request body, the evaluation runs asynchronously and you will be notified when it's completed. The immediate response confirms this, it returns a success message stating the evaluation started and you'll be notified when it's completed, along with an evalId, credits used, and an isProcessing flag.

That isProcessing flag is the hook for a hybrid approach, your pipeline can poll it opportunistically while also registering a callback URL for push notification rather than choosing one exclusively. The Skills documentation shows the polling variant as the default agent pattern, upload a file to get a projectId, create an order to get an orderId, monitor status by polling until "completed," run a quality check for scores and segment analysis, report issues via revision creation, and optionally upgrade to human review. For high-volume CI/CD pipelines, though, polling every order status on an interval doesn't scale, a webhook-driven design where your system reacts to completion events is the pattern worth building toward, and the retry and timeout behavior for those callbacks is documented in the callbacks reference rather than something to assume from general REST conventions.

The design decision for your team, concretely: use synchronous status checks for low-volume, interactive flows, a content editor manually kicking off a translation and waiting, and use callback-driven completion events for anything running inside a batch pipeline or triggered by a content-management webhook of your own. Mixing both, poll on job creation to confirm acceptance, then let the callback drive the completion event, is a reasonable middle path and matches how the QC endpoint is already structured.

A reference architecture for wiring this into existing pipelines

A CI/CD-integrated localization flow built on this object model looks roughly like this:

[Content Source: CMS / Git repo / video asset store]
|
v
[Trigger: commit hook, CMS webhook, or scheduled job]
|
v
[Ollang Upload] --------------> returns projectId
|
v
[Ollang Create Order] ---------> returns orderId(s)
(folder assigned for namespace,
order type + target languages set,
Level 1 review gate flag set per content class)
|
v
[Async wait: callbackUrl registered OR poll order status]
|
v
[Order completed] -----> [Run QC Evaluation] --> QC score + human-edit-% written to internal metrics store
|
v
[Gate logic in your pipeline]
score >= threshold --> auto-publish to target locale
score < threshold --> [Request Human Review] --> re-poll --> publish on completion
|
v
[Revision loop if downstream QA flags issues]
--> [Create Revision] --> re-run --> re-check QC

Every box after "Trigger" is a call against the same four objects, project, order, QC result, revision, regardless of whether the content is a marketing PDF, a product video, or a JSON strings file for a mobile app. You are not switching data models when you switch modality. Levels and review gates as first-class objects give you one integration surface, several quality tiers, and no branching logic in your own codebase to accommodate them. Implementation-level specifics, auth headers, pagination parameters, exact retry semantics, live in Ollang's API documentation and should be your source of truth before you commit to this shape in production.

The actual argument

This data model matters more than feature comparisons because it determines whether localization behaves like infrastructure or like a queue of favors. A folder-project-order hierarchy with queryable QC and revision data, review gates that toggle without reshaping calls, and a callback model built for asynchronous completion is a signal that the platform was designed to be invoked by systems, not staffed by project managers. Anything that fits into a Trigger → Order → Callback → Gate shape composes with CI/CD, with agent-driven workflows, with retry logic your team already understands. Anything that doesn't will eventually force you to build a translation layer between your pipeline and the vendor's ticketing mentality, and that translation layer is the manual overhead localization infrastructure is supposed to remove.