Skip to main content
Automated translations are available as a paid add-on to Growth, Pro, and Enterprise plans. Please contact sales for more information.

​
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.
Translations dashboard in light mode

​
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.
An automated translation is stored under a directory named after the language code that you have selected.Custom directory names for translations are not supported at this time.

​
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.
Mintlify will never automatically publish translations to production. You must review and merge each translation pull request before the changes are live.
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

The translation service translates all non-code, non-component content in your documentation. This includes:
  • Text
  • Links
  • Titles and descriptions in frontmatter
  • Component attributes
  • Navigation labels
The service does not translate:
  • Code blocks
  • Images or other media
  • Metadata
If you need to modify your translations, make any changes directly in the translation pull requests created by the translation service.Any manual changes may be overwritten the next time the English version of the page is updated and the translation job runs.
Check these common issues:
  • Verify that your translation subscription is active for the language.
  • Confirm that your content uses valid MDX formatting.
  • Confirm that your docs.json file is properly configured.
If you’re still running into problems, please contact support.
The translation system operates at the page level, and will attempt to translate entire pages when any portion changes.This approach ensures that the translation is as accurate as possible and removes the need for manual updates to localized files.
We offer translations for all languages supported by the languages feature.If the language you’d like to translate to is not listed, please contact support and we’ll be happy to assist.
The translation service does not support custom translation rules for specific terms or phrases. We are developing this feature for a future release.
⌘I