Translations

​

Overview

You can automatically translate your documentation into multiple languages while maintaining structure, formatting, and links with AI. Translations integrate with the languages feature, allowing readers to switch between available languages in your documentation.

​

Prerequisites

• You must have a Growth, Pro, or Enterprise plan and translation add-ons for your target languages.
• You must use GitHub as your repository provider for your documentation content.
• Your documentation must use English as a base language.
• You must have a valid docs.json file in your repository.
• All content to be translated must use valid MDX formatting. Any invalid MDX will cause the translation to fail.

​

Getting Started

Start with a complete translation of your documentation into each of your preferred languages. This approach ensures complete coverage in each language and automatically updates your docs.json file.

You can initiate a complete translation from the translations page in your dashboard.

1. Select Start translation.
2. Select the first language that you want to translate your content to and then select Start translation.
3. The translation process will create a new branch and pull request in your Mintlify project repository with the translated content. Larger documentation sets may take longer to process.
4. Review the pull request and merge it.
5. Repeat the process for each language that you want to translate to.

​

Ongoing Translations

After adding a translation to your docs.json file, any future changes to your documentation are automatically translated as long as you maintain a subscription to the translation add-on for your configured languages.

The ongoing translation process follows this sequence:

1. A member of your organization makes changes to the documentation in your repository.
2. When the changes are pushed or merged into your main branch, the ongoing translation job is triggered.
3. The translation job updates, removes, or creates the required files in all subscribed languages based on your docs.json file.
4. The translation job creates a separate branch and pull request containing the translated changes for your review.

The automatic translation job doesn’t handle manual changes to the localized files or the docs.json navigation trees well. Make all changes in your English content and let the translation service manage the localized versions.

We recommend promptly reviewing and merging translation pull requests so that your localizations are kept in sync.

​

Troubleshooting and FAQs