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.

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.

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.

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.

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 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.