# Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/translations.md

# Source: https://gitbook.com/docs/documentation/ja-gitbook-documentation/gitbook-agent/translations.md

# Source: https://gitbook.com/docs/documentation/zh/gitbook-dai-li-agent/translations.md

# Source: https://gitbook.com/docs/documentation/fr/agent-gitbook/translations.md

# Source: https://gitbook.com/docs/gitbook-agent/translations.md

# Translations

{% hint style="warning" %}
Auto translations are currently in Beta. [Let us know](https://www.gitbook.com/contact) if you have any feedback or encounter any issues.
{% endhint %}

{% hint style="info" %}
Only [organization admins](https://gitbook.com/docs/account-management/member-management/roles#admin) can create and access translations, as it’s [a billable feature](#pricing).
{% endhint %}

Auto translations make it easy to keep your documentation up-to-date in multiple languages, with minimal manual effort. You can create a space as a translation of another, and let GitBook Agent handle the rest.

<figure><img src="https://1050631731-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FhOOp6fNMYks6U4M6UXTO%2FCreate%20translation%402x.png?alt=media&#x26;token=a142a9cd-6ecd-49c4-9670-2226897afc1f" alt=""><figcaption></figcaption></figure>

## How translations work

* **Create a translation space:** Set up a new space as a translation of an existing one. Choose your source space and target language.
* **Continuous updates:** Every time you make changes to the source content, the translation workflow only runs for the **pages that have been changed**.
* **Automatic sync:** After changes are merged, the translation workflow **runs automatically** and syncs with its source, so your translated space always reflects the latest updates.

## Set up an auto translation

To translate a space to a new language, start by creating a new [space](https://gitbook.com/docs/creating-content/content-structure/space#create-a-space) in your organization. From the modal that appears, click **Translation** from the quick actions menu.

From the modal that appears, you’ll need to choose a:

* Source
* Source language
* Target language

These options will be used to translate your space into a duplicated, translated space in your organization. You’ll also see a quick overview on the cost of translating your space.

### Advanced configuration

**Custom AI instructions:** Add advanced instructions to guide the AI on tone of voice, style, or other preferences. This helps ensure your translations match your brand or audience.

{% hint style="info" %}
Adding custom instructions to your translation workflow can be helpful, but is limited in certain cases.

Custom instructions cannot be used to create new elements on a translated space, add extra text, or change the structure of the source content.
{% endhint %}

**Glossary support:** Define a glossary to control how specific terms are translated. This keeps terminology consistent across all supported languages.

{% hint style="warning" %}
**Changing your glossary will trigger a full re-translation of your content**. There is currently no workaround: we cannot reliably detect which pages might contain a glossary keyword, so the safest approach is to re-translate all pages. Updating the glossary may therefore be time- and cost-intensive.
{% endhint %}

## Add a translation to a variant

After creating a translation, you’ll be able to add it to published docs site as a [variant](https://gitbook.com/docs/publishing-documentation/site-structure/variants). This will allow users to toggle between languages in the upper right corner when viewing your main docs site.

{% hint style="info" %}
To provide the best experience for your users, you’re able to set the default language of a variant when setting it in your settings.

It’s best practice to add the language of your translated space when setting up your variant.
{% endhint %}

Head to your site settings, under the structure tab to set up a new variant for any translations you have.

## Pricing

Translations are a paid **monthly** add-on:

* $25 for up to 50,000 translated words
* $0.20 per additional 1,000 words

Each month includes 50,000 words of translation for $25. After that, every additional 1,000 words costs $0.20. Your 50,000-word allowance resets at the start of each month.

In your first translation, every word will count towards your bill. After that, only **pages** with new or updated words are charged. For example, if you edit your docs later, only the pages with new words will count towards your word limit — you won’t be re-billed for the entire document.

{% hint style="warning" %}
Be cautious when working on multiple translations with large pages, as translated word count includes all words within a page that contains a change — meaning if only a few words are changed in a large page, the entire page will be re-translated.
{% endhint %}

## FAQ

<details>

<summary>Why use auto-translations?</summary>

* **Effortless multilingual docs:** Reach a global audience without manual translation work.
* **Smart updates:** Only changed pages are re-translated, saving time and resources.
* **Full control:** Customize translations with advanced instructions and glossary management.

</details>

<details>

<summary>Can I edit the translation?</summary>

You currently can't edit translations.

As translations are done as a pure transformation of the source content, we can't reconcile potential edits made on the translation result with a new translation.

To workaround it, we recommend the following flow:

* Use the glossary to define specific translations that you want the AI to use
* Use the custom instructions to iterate on the output

</details>

<details>

<summary>How many translations do I need to create?</summary>

You should only create **one translation workflow per language** of any given source content. Creating multiple workflows will accrue extra, duplicated costs in your organization.

</details>

<details>

<summary>What are some current limitations?</summary>

* Translations do not localize UI elements in your variant automatically. Head to your site’s customization settings to [localize the interface](https://gitbook.com/docs/publishing-documentation/customization/extra-configuration#localize-user-interface) for a [specific variant](https://gitbook.com/docs/publishing-documentation/customization#customizing-sites-with-multiple-sections).
  * This includes user-input customizations, such as announcement banners.
* Translations cannot add extra content to the page - like a hint or a banner noting that a page was translated by AI. Consider adding an extra page in the translated space to note this, or the [announcement banner](https://gitbook.com/docs/publishing-documentation/customization/layout-and-structure#announcement-premium-and-ultimate) in your site variant.
* Changing the glossary triggers a full re-translation of all pages, which can increase processing time and cost. There is no partial re-translation based on glossary usage at this time.

</details>

If you need help getting started or want to learn more about configuring auto-translations, [contact our support team](https://gitbook.com/docs/help-center/further-help/how-do-i-contact-support).