Human review

Max PrilutskiyCEO & Co-Founder7 min read

Most of your content can ship the moment the engine returns it. Some can't. A regulated disclosure, a medical instruction, a headline that carries the brand – for those, you want a person to read the translation and sign off before it goes live, not after a customer files a complaint.

The usual way to get a human into an automated flow is the painful way: hold the request open while someone reads, or build your own review queue, or hand-wire a translation vendor's API. This stage does it inside the job. When humanEdit is enabled, the async job runs the engine, then pauses on a person – your own team or an external professional – and resumes with their edit, carrying that output forward to any stages that follow.

It runs after Rephrase and before Post-edit in the localization pipeline and, like every stage, applies only to jobs created through the Async Localization API. New to the pipeline? Start with the overview.

On this page

How the pause works#

After the core translate step – and after Rephrase, when that stage is on – the job hands the AI translation to a human for review. The reviewer reads it, then either approves it as-is or submits an edited version. Only then does the job continue. The human output – approved or edited – becomes the input to every later stage and, ultimately, the job's outputData.

The obvious objection to pausing a job for minutes, hours, or a day is cost: a request held open is a resource burning while nothing happens. This stage does not work that way.

The wait is event-driven, not a held-open connection

The workflow resumes on an event – a reviewer submitting in the dashboard (Internal Review) or a callback from the translation provider (External Review). It is not polling on a tight loop and it is not holding a connection open, so a long timeout consumes no compute in the background. A job can wait 48 hours for a human the same way it waits on a model: it is parked, not spinning.

Who does the reading is set per language and directory: the engine's Human review settings send each one to a decision pool – your own team or an external provider. The pause, resume, and carry-forward behavior is identical either way, and translations no pool covers ship without review.

Internal Review#

Your own team reviews translations directly in the Lingo.dev dashboard. Pending reviews appear in the Queue (/orgs/<org-id>/queue) as Human review items, and reviewers are notified when new items arrive. A reviewer opens an item, edits whichever keys need it, then clicks Approve as-is or, once something is edited, Approve with edits – the button counts them, as in Approve with 2 edits. The job resumes with their output.

There is no claim or lock. Which decision pool a review goes to decides who is emailed about it; anyone with Review translations can see and decide any open review.

Internal Review comes with the Enterprise plan. On a plan that includes it, a new engine starts on Internal Review; on one that doesn't, it starts on External Review, and the Internal review option carries an Enterprise tag. Reach for it when your team has the language expertise in-house and you want full control over the final wording, with no third party in the loop.

Permissions#

Internal review is not open to everyone in the organization – the review queue is permission-gated, so a translation in review is visible only to the people you grant access. An organization admin assigns access through roles (Settings → Roles):

PermissionWhat it unlocks
Review translations (engine:review_translations)See Human review items in the Queue, edit them, and approve them as-is or with edits
Manage reviews (org:manage_reviews)Review history and statistics for internal reviews. Without it, decided reviews stay hidden in the Queue

The two permissions are deliberately separate. A reviewer needs only Review translations – that single grant is the whole job: edit, approve as-is, approve with edits. Manage reviews is for whoever oversees the operation; it adds the review history across the org but does not include queue access on its own. Grant both to a lead who reviews and reports; grant only the first to someone who only works the queue.

External Review#

When you don't have in-house reviewers for a locale, route it to an external decision pool – on Lingo.dev's account or your own provider account, such as BLEND – and the translation is submitted to a qualified professional translator instead. The job pauses the same way; it resumes when the provider returns the edited translation. Nothing about your code changes – the difference is who reads the string, not how the job behaves.

There is no tier to pick – the marketplace grades the translator itself. External Review is billed per word: through your Lingo.dev plan on Lingo.dev's account, or by the provider on your own account.

An external review shows up in the Queue as well; opened, it names a Qualified translator as its reviewer. Someone with Review translations can open it and take it over: pick Approve as-is or Approve with edits, and the job finishes there instead of waiting for the translator. The Take over this review confirmation says what it costs before you commit – taking over is free only while no translator has started; once one has, the translator fee stands whether or not you use their work.

This is the candor worth being explicit about: External Review is a real human translator on the other end, with the turnaround and cost that implies. It is not a faster model. Use it where a person's judgment is the point – regulated text, high-stakes copy – and lean on the AI-only path for the bulk of your content that doesn't need it.

Quality threshold#

Not every translation needs a person. Set Quality threshold (1–100) in the Human review settings and an AI reviewer scores each translation before it goes to review. At or above the threshold, the translation ships without a human and the humanEdit step is recorded as skipped; below it, the translation goes to review as usual. Leave the field empty to review everything. In the config it is qualityThreshold on humanEdit.

A translation that ships this way has no human output, so Post-edit does not run on it.

Timeout#

A human stage introduces a risk the AI stages don't have: the human might never respond. A reviewer is on vacation, the provider is backed up, the item is forgotten. Left unbounded, the job would wait forever.

So the wait is bounded. You set how long the workflow waits for the human output – Timeout, in hours, in the Human review settings; timeoutHours in the config. It applies to both review modes. If the timeout expires with no response, the stage is marked skipped and the job continues with the AI translation as the final output. The default is 48 hours. In the Queue, a review that timed out reads Closed without a decision.

State the cost plainly: on timeout you ship the unreviewed AI translation. That is the correct fallback for most content – a translation that shipped beats a job stuck open indefinitely – but it is a real tradeoff. For content where a human must sign off no matter what, set a generous timeout and alert on the skip; for content where review is a nice-to-have, a short timeout keeps the pipeline moving.

Timeout is per stage, not per job

The timeout governs only how long this stage waits for a human. It is independent of how long the rest of the job takes. Because the wait is event-driven, a long timeout costs you latency-to-final-output if the reviewer is slow – never background compute.

Enabling the stage#

humanEdit is configured on the engine, in its Pipeline tab. How pipeline stages are configured in general is on Configure the pipeline; the shape specific to this stage is:

json
{
  "humanEdit": {
    "enabled": true,
    "timeoutHours": 48,
    "qualityThreshold": 85,
    "routes": [
      { "pool": "<legal-reviewers-pool-id>", "match": { "locales": ["de"], "path": ["docs/legal/**"] } },
      { "pool": "<lingo-external-pool-id>", "match": { "locales": [] } }
    ]
  }
}

routes sends each language and directory to a decision pool: locales empty means any language, and path omitted means any directory. The most specific route wins, and a target no route covers ships without review. provider and tier are legacy fields, read only while routes is empty. timeoutHours is the bound from Timeout, and the optional qualityThreshold (1–100) is the one from Quality threshold.

A job can't start while a route points to an archived or deleted pool – it fails with HumanReviewPoolUnusable until the engine routes to another pool.

When the stage runs, it records itself on the job under stepId: "humanEdit" with a status of completed, failed, or skipped – the same step record every stage produces. Reading those records is covered in Observe pipeline runs.

A human edit can drift from your engine rules

A human translator may phrase something in a way that conflicts with your glossary, brand voice, or rules – they're translating well, not memorizing your config. To reconcile the human's edit back to your engine rules automatically, enable the next stage, AI review – Post-edit in the Pipeline tab. It runs only after a human stage that actually produced output.

Next steps#