# Translate a document

## Overview

A document translation is the language-specific version of an existing document. Use the
translation editor to edit the translated title or content and save the result as a draft or a
published variant.

| If you need to… | Go to |
|---|---|
| Understand the source and translation panes | [Understand the translation editor](#understand-the-translation-editor) |
| Edit a title or translation | [Edit and save a translation](#edit-and-save-a-translation) |
| Handle a new, stale, or machine-translated variant | [Handle translation branches](#handle-translation-branches) |
| Resolve a message that stops the task | [When translation fails or is incomplete](#when-translation-fails-or-is-incomplete) |
| Return to the project translations list | [Know what happens next](#know-what-happens-next) |
| Find documents before opening a translation | [Documents overview](doc:documents-overview) |
| Continue with reader-facing published content | [Published documentation](doc:published-documentation) |
| Review document states and actions | [Document changes](doc:document-changes) |

## Before you start

**Prerequisites**

- Have the existing document record available.
- Know the target language. The editor receives it through the `lang` query parameter.
- Wait for the document-language pair to load before editing.

The editor loads only when a document ID and a non-empty target language are available. After the
pair loads, the existing variant title and content fill the editable fields when there are no
unsaved edits.

With the document and language ready, find and open the translation editor.

## Find and open the document

The project translations list shows documents for a selected language and opens the corresponding
language-specific editor.

**Steps**

1. Open the project translations list.
2. Select the language whose document variant you want to edit.
3. Select the document in the language's page list.
4. Check that the translation editor shows the selected document and language.

**Result:** The editor opens for the selected document and language. Select **Translations** in the
header to return to the project's translations tab.

## Understand the translation editor

The translation editor places the source beside the editable language variant so you can compare
the two versions while working.

| Area | What you use it for |
|---|---|
| **Source** pane | Read the source title and source content. |
| **Translation** pane | Edit the translated title and translated content. |
| Status strip | Check whether a variant is a draft, published, machine-translated, or stale. |
| Header actions | Return to **Translations**, queue **AI translate**, **Save draft**, **Unpublish** a published variant, or select **Save & publish**. |

The source content is displayed in a read-only textarea. The translation title is an editable text
field, and the translation content is an editable textarea. Keep directive lines such as
`:::tabs` and `::include{…}` and code blocks exactly as they appear in the source.

The status strip changes with the loaded variant. A variant can show its status, a
`machine-translated` indicator when it was produced by machine translation, and a
`stale — the source changed since this translation was saved` indicator when the source changed
after the translation was saved. When no variant exists, the strip says `No variant yet — write
one or use AI translate.`

**Result:** You can compare the source pane with the editable translation pane and choose the action
that matches the variant's status.

## Edit and save a translation

Editing a translation changes the language variant while leaving the source pane available for
comparison.

**Prerequisites**

- The translation editor is open for the document and target language.
- The translation content is ready to save.

**Steps**

1. In the **Translation** pane, enter the translated title in the title field.
2. In the **Translation** pane, enter the translated document in the content field and leave
   directive lines and code blocks unchanged.
3. Choose one save action:

   | If you need to… | Select |
   |---|---|
   | Keep the variant as a draft | **Save draft** |
   | Make the variant serve readers in the target language | **Save & publish** |

4. Check the notice that appears after the save action.

**Result:** A draft save displays `Draft saved.` A published save displays the individually quoted
notice `Published — the variant now serves readers in this language.`

If the content field is empty when you save, the editor displays `Translation content is empty`.
Add translated content before selecting a save action.

## Handle translation branches

The status shown in the editor tells you which translation path applies to the current variant.

| What you see | What to do |
|---|---|
| `No variant yet — write one or use AI translate.` | Enter a translation yourself or select **AI translate**. |
| `machine-translated` | Review the machine-produced title and content before saving or publishing. |
| `stale — the source changed since this translation was saved` | Compare the source and translation, then update the translation before publishing it. |
| A published status | Select **Unpublish** when the variant must return to draft status. |
| `Translating…` | Wait until the AI translation request finishes. |
| `Saving…` | Wait until the save request finishes. |
| `Publishing…` | Wait until the publish request finishes. |

To queue a machine translation:

**Steps**

1. Select **AI translate**.
2. Check that `AI translation queued — directives and code blocks are preserved verbatim…` appears.
3. Check that the updated variant replaces the previous content.

**Result:** The editor displays `AI translation complete and published (directive check passed).`
when the directive check passes. It displays `AI translation saved as DRAFT — the directive-preservation check flagged it for review.`
when the check flags the translation. If the polling period ends first, it displays `Still translating in the background — reload the page later.`

To return a published variant to draft status:

**Steps**

1. Select **Unpublish** when the status is published.
2. Check that the editor reloads the document-language pair and displays the resulting notice.

**Result:** The editor displays `Variant unpublished (draft).`

## When translation fails or is incomplete

Use the message text to identify what stopped the translation task and what to do next.

| Message | Meaning | Next action |
|---|---|---|
| `Missing ?lang= parameter.` | The editor has no target language in the address. | Open the editor from a language-specific project translation list. |
| `Loading translation editor…` | The translation pair is still loading. | Wait for the editor to finish loading. |
| `Translation editor failed to load.` | The pair could not be loaded or was not found. | Return to the project translations list and open the document again. |
| `Translation content is empty` | The content field has no non-whitespace content. | Enter translated content before saving. |
| `Save failed` | The save request failed without a more specific API message. | Check the content and try the save action again. |
| `AI translate failed to queue` | The machine-translation request could not be queued. | Try **AI translate** again after the editor is ready. |
| `Unpublish failed` | The unpublish request failed without a more specific API message. | Check the current status and try **Unpublish** again. |
| `Save failed` fallback; API errors may replace it. | The save request failed without a more specific API message. | Check the content and try the save action again. |
| `AI translate failed to queue` fallback; API errors may replace it. | The machine-translation request could not be queued. | Try **AI translate** again after the editor is ready. |
| `Unpublish failed` fallback; API errors may replace it. | The unpublish request failed without a more specific API message. | Check the current status and try **Unpublish** again. |
| `AI translation complete and published (directive check passed).` | The AI translation completed and passed the directive check. | Check the published variant. |
| `AI translation saved as DRAFT — the directive-preservation check flagged it for review.` | The AI translation was saved as a draft for review. | Review the translation before publishing it. |
| `Published — the variant now serves readers in this language.` | The variant was published. | Check the published variant. |
| `Translating…` | AI translation is in progress. | Check the editor for the completed or draft result. |
| `Saving…` | A save request is in progress. | Check the editor for the save notice. |
| `Publishing…` | A publish request is in progress. | Check the editor for the publication notice. |
| `Translating…`, `Saving…`, `Publishing…` | One of the header actions is in progress. | Check the editor after the action finishes. |
| `Still translating in the background — reload the page later.` | The editor stopped polling before the updated variant arrived. | Reload the page later. |

## Know what happens next

The translation editor keeps the source document and its language variant together while you work.
After saving, the status and notice tell you whether the variant is a draft or published.

1. Select **Translations** to return to the project's translations tab.
2. If the result is a draft, continue reviewing and editing it in the translation editor.
3. If the result is published, continue to [Published documentation](doc:published-documentation)
   to work with the reader-facing variant.

**Result:** You return to the project's translations list or leave the editor with the saved variant
in its displayed status.