Integrate human review into API jobs
Route translations to reviewers, track their decisions, and collect the final document outputs.
Add human review when a translation needs a person's judgment before delivery. The engine routes each document and target language to a decision pool; reviewers approve or edit eligible units, then the pipeline continues toward a downloadable file.
Begin with a working API translation. You also need the plan features for human review, a decision pool, and a reviewer with access to the engine's translations.
Configure the review before starting #
Open the engine's Pipeline tab and enable Human review. Select a decision pool, languages, and any directory scope. Directory routing matches the key you send for each document, so use stable paths such as emails/order-confirmation.json.
For review of all newly translated content in the route, choose Everything, which leaves the quality gate off. To review selectively, choose Strict, Medium, or Lax. The gate lists errors with severities and categories; the level decides which severities need review. A translation the gate could not check goes to review too. See quality gate levels for the descriptions. Reused translations provide read-only context and do not automatically become new review work.
Choose a timeout appropriate to the review team. The deadline starts when the target is ready, and unanswered units can continue with their preceding translations after it expires. If every published translation must have a human decision, your application's publication check must enforce that requirement.
Configure the pipeline through the API when engine setup is part of your application.
Submit the content #
Create the job, upload missing artifacts, and call /start. Save its ID with the source revision and intended review policy. The engine's pipeline configuration is captured at start; later changes do not modify the running job's review policy.
Read the job's document IDs and target locales. humanEdit in the target's stage progress identifies review work, while the review API provides the actual units and decisions. A job can remain Running while reviewers work.
Give a reviewer the required context #
Reviewers can use Queue → Kind → Human review in the dashboard, where quality-gate findings appear next to the translation. They can approve without changes or edit the translations before submitting. Keep the source, target language, placeholders, and intended terminology visible to the reviewer.
For an application-owned review interface, list open reviews with GET /v2/organizations/:orgId/localization/reviews, then retrieve the selected document/locale review. Authenticate decisions as the reviewer using a personal key or user session, not the background service's organization key.
Submit Approved or Edited decisions for required units. Internal reviews allow partial submissions. Taking over an external review requires a decision for every remaining required unit at once and may still incur the provider's charge. The review reference covers exact payloads and errors.
Collect and validate the final result #
After a reviewer submits, continue retrieving the localization job. Download the target only once its status is Completed. Review completion and file completion are separate because post-edit, length handling, or back-translation may still run.
If you require the exact wording a person approved, disable later rewriting stages and inspect the final output. If you require proof of approval, check review decisions and timed-out units rather than treating a completed stage as evidence that a person approved every unit.
Publish only when the source revision still matches and the required review policy was met. A late translation must not replace output for a newer source revision.
Recover interruptions #
Keep the original job and review identities after a client timeout. A new job starts a separate translation and review process. If a decision response is lost, retrieve the review and check its saved decisions and reviewer IDs. The same reviewer can repeat an identical decision while the target still accepts submissions, but a completed target can return 409 even when the first submission succeeded. Successful decisions are final.
At a review deadline, inspect accepted decisions, unanswered units, and the resulting file. Preserve completed work and deliberately choose the next action: hold publication, obtain another review, or accept an explicitly defined fallback.