Configure the translation pipeline
Save the engine's stages before starting a job and inspect the stages that actually run.
A localization job uses the engine's pipeline configuration captured when you start it. Configure the engine before calling /start. Later engine edits affect future starts, not the snapshot of an already running job.
Open the engine's Pipeline tab in Studio, or update pipelineConfig through PATCH /v2/engines/:id. The caller needs permission to edit the engine. The organization needs access to the features for stages that can run. See feature access and pricing.
Save a complete configuration #
Read the engine with GET /v2/engines/:id before changing an existing configuration. Sending pipelineConfig replaces that configuration; omitted stages receive their defaults. Preserve the settings you intend to keep.
This request configures translation with a rephrase pass. Optional stages omitted from it are disabled:
PATCH /v2/engines/:id
Content-Type: application/json
X-API-Key: YOUR_API_KEY{
"pipelineConfig": {
"localize": { "enabled": true },
"rephrase": { "enabled": true }
}
}Use a separate engine when an application needs a different policy for a class of jobs. Configure its models and guidance, then select its ID when creating those jobs.
Stage settings #
Field in pipelineConfig | Settings |
|---|---|
localize | enabled: true. Translation is required. |
preEdit, rephrase, postEdit, backTranslation | enabled boolean. Defaults to false. |
qualityGate | enabled boolean and strictness: "strict", "medium", or "lax" (default "medium"). |
humanEdit | enabled, positive integer timeoutHours (default 48), and review routes. |
contentLength | enabled and a mode described below. |
Post-edit requires human review. A post-edit pass runs on human output; a bypass or timeout can leave no human output to refine.
Content-length modes are { "_tag": "noLongerThanSource" } (the default), { "_tag": "fixedCap", "maxColumns": 40 }, or { "_tag": "matchSource", "tolerancePct": 10 }. Numeric values must be positive integers. These are display-column targets, not byte limits or guaranteed UI fit.
Route human review #
Create or select decision pools first. Each humanEdit.routes entry names a pool and its language and directory scope. This configuration sends all newly translated content to one pool:
{
"pipelineConfig": {
"localize": { "enabled": true },
"humanEdit": {
"enabled": true,
"timeoutHours": 48,
"routes": [
{
"pool": "YOUR_DECISION_POOL_ID",
"match": { "locales": [] }
}
]
}
}
}An empty locales array covers all languages. Add "path": ["emails/**"] inside match to cover documents under that directory; it matches the document's key. Paths name literal directories followed by /**. A route without path applies across directories. More specific directory and locale matches take precedence; conflicting routes are rejected.
To review selectively, enable human review and add a route that covers the translations you want reviewed. Add qualityGate inside pipelineConfig and keep the other settings:
{
"qualityGate": { "enabled": true, "strictness": "medium" }
}You can save an enabled qualityGate while humanEdit.enabled is false. Studio keeps the saved setting when you turn human review off and back on. With the API, include qualityGate in each replacement pipelineConfig to keep it. The gate runs only if human review is enabled in the job's resolved pipeline.
The gate stores findings for each unit. "strict" requires review for any finding, "medium" for major or critical findings, and "lax" for critical findings only. A translation the gate could not check still requires review. Set qualityGate.enabled to false for Everything, which sends every new translation covered by a route to review. Reused translations do not become new review work.
The judgement does not depend on strictness; the level is applied to the findings. Changing an engine's level affects future job starts, not an already running job's captured configuration. See quality gate levels for the descriptions and severity definitions.
The legacy Async Localization API still accepts humanEdit.qualityThreshold, but ignores it. Every translation in a language selected for human review goes to a reviewer. For selective review in the current pipeline, set Review level in the engine's Human review settings.
Review availability depends on the organization's plan and the pool's provider connection. At start, unavailable stage features are turned off along with stages that depend on them. Read the job's target stages to confirm the effective workflow. If publication requires a human decision, enforce that policy before delivering the downloaded output.
Inspect the result #
The quality-gate stage stores this output for each checked unit:
{
"findings": [
{
"span": "Pay €20",
"reason": "The translation changes the source amount from €10 to €20.",
"category": "accuracy",
"severity": "critical"
}
]
}span is quoted verbatim from the translation the gate judged. reason is one English sentence. Categories are accuracy, terminology, guidance, fluency, and style; severities are critical, major, and minor. An empty findings array means the gate found no errors. Review units return this output as quality; see human review. Reviewers see the findings next to the translation in the Queue.
Stage progress distinguishes completed, skipped, failed, and warned work. Human review describes decisions and deadlines. The pipeline guide explains why each stage might be useful and how later stages can change earlier text.