Rephrase for natural copy

The translation is accurate, the glossary terms are right, and it still reads like a translation. Rephrase is the pipeline stage that closes that last gap: an AI agent rewrites the current output so it reads like native copy in the target locale, while preserving the meaning, the placeholders, and the tags.

This page covers the rephrase stage on its own – what it rewrites, what it leaves untouched, what happens when the pass fails, and the one decision it puts in front of you: enable it or skip it. New to the pipeline? Start with the Async Localization Pipeline overview for how the stages fit together. Rephrase is async-only – it runs for jobs created through the Async Localization API, never for the synchronous /localize call.

What it does#

A literal translation can carry the source's phrasing into the target locale – grammatically correct, but recognizably translated. The rephrase stage rewrites the current best output so it reads like native copy: natural and idiomatic in the target locale, preferring an idiomatic equivalent over a word-for-word rendering. It preserves the original meaning and intent, and it applies your engine's glossary, brand voice, and instructions – the same configuration that produced the translation governs the rewrite.

It runs after the AI and human refinement steps, on whatever output reached it. So it works the same whether or not human review and AI post-edit are enabled – it rewrites the current best version either way. When the back-translation check is also enabled, it verifies the rephrased output, not the pre-rephrase one.

A literal pass keeps you close to the source wording; rephrase moves the copy toward how a native writer would phrase it. Therefore the two aren't interchangeable – which you want is the decision below.

Your placeholders and tags survive#

The obvious worry about a stage whose job is to rewrite text: will it touch the parts that are not prose? It does not. Rephrase keeps placeholders, variables, tags, and formatting exactly as-is – it rewrites the words around them, not the tokens your app depends on.

So a string like this keeps every interpolation and every tag, and only the human-readable copy changes:

Source (en):        "Hi {firstName}, you have <b>{count}</b> new messages."
Translated (de):    "Hallo {firstName}, du hast <b>{count}</b> neue Nachrichten."
After rephrase (de):"Hey {firstName}, <b>{count}</b> neue Nachrichten warten auf dich."

{firstName}, {count}, and the <b> tags are identical across all three. The copy reads more natural in German; the structure the runtime relies on is unchanged.

When it fails, the job does not#

Rephrase is a non-critical stage. An AI rewrite can fail or time out – and when it does, the translation you already paid for is not lost. The previous output carries forward unchanged and the job continues. You are not gambling an accurate translation on a stylistic pass.

A failed rephrase does not fail the job. It surfaces as a step record with status: failed, the job finishes as completed_with_warnings, and the pre-rephrase translation is what lands in outputData:

{
  "id": "ljb_C3d4E5f6G7h8I9j0",
  "status": "completed_with_warnings",
  "outputData": {
    "greeting": "Hallo {firstName}, du hast <b>{count}</b> neue Nachrichten."
  },
  "warnings": [
    { "step": "rephrase", "message": "<the failure reason for this step>" }
  ],
  "steps": [
    { "stepId": "localize", "type": "action", "status": "completed" },
    { "stepId": "rephrase", "type": "action", "status": "failed" }
  ]
}

The de translation shipped. The exact message text is illustrative here – what is fixed is the shape: a warnings[] entry with step and message, the rephrase step recorded as failed, and the pre-rephrase output preserved in outputData. Read the step field to see the copy was not polished on this run, so you can re-run that locale if natural phrasing matters for it. See Observe pipeline runs for the full steps[] and warnings shape, and how non-critical failures roll up to completed_with_warnings.

When to enable, when to skip#

Rephrase optimizes for one thing: reading like a native original. That is exactly right for some content and exactly wrong for other content, so this is a per-content decision, not a global default.

Enable it for marketing copy, landing pages, product descriptions, and onboarding – anywhere reading like native copy matters more than staying close to the source phrasing.

Skip it for technical and legal content, where literal accuracy is the priority. Rephrase rewrites wording to sound natural; in a contract clause, an API reference, or a compliance string, the wording closer to the source is the safer one. For that content, leave rephrase off and let the core localization step's output stand.

Turning it on#

Rephrase is configured like every other stage – an engine-level default plus an optional per-request override – so the full mechanics live on Configure the pipeline. The short version: toggle it in the engine's Pipeline tab to apply it to every job, or set it for a single submission with pipelineConfig:

{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "data": { "headline": "Ship global products faster." },
  "pipelineConfig": {
    "rephrase": { "enabled": true }
  }
}

Stages you omit inherit the engine config – so the override above turns rephrase on for this submission without touching any other stage. That is what lets you keep rephrase off on the engine for literal content and switch it on per request for the marketing payloads that want it.

Next steps#