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.

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

​
Writing content to be translated

To make your documentation more translatable and easier to read in English, avoid these common patterns:

  • Wordiness: Redundant sentences are more difficult to comprehend and translate.
    • Avoid: “In order to be able to successfully complete the installation process…”
    • Better: “To install the software…”
  • Passive voice: Passive voice makes it unclear who performs an action.
    • Avoid: “The configuration file should be updated by the administrator.”
    • Better: “The administrator should update the configuration file.”
  • Negative sentences: Tell people what to do rather than what not to do.
    • Avoid: “Don’t forget to not skip the configuration step.”
    • Better: “Remember to complete the configuration step.”
  • Pronouns: Words like “it,” “this,” and “that” can be unclear about what they reference, especially if a sentence uses many pronouns. Use specific nouns instead.
    • Avoid: “Configure the database connection. After you do this, it will work properly.”
    • Better: “Configure the database connection. After you configure the connection, the database will work properly.”
    • Avoid: “When you configure it, make sure it connects to them properly so they can communicate with each other.”
    • Better: “When you configure the database, make sure the database connects to the servers properly so the servers can communicate with each other.”
  • Ambiguous link anchors: Accurately describe where a link goes and avoid ambiguous link anchors like Click here. When possible, use the exact title of the page or resource that a link points to.
    • Avoid: “Click [here](path/to/getting-started-guide) to learn more about the setup process.”
    • Better: “Learn more about the setup process in our [getting started guide](path/to/getting-started-guide).”
  • Nominalizations: Verbs or adjectives turned into nouns, often ending in -ion, -ment, or -ness. Use active verbs instead.
    • Avoid: “The configuration of your navigation requires a valid docs.json.”
    • Better: “You must have a valid docs.json to configure your navigation.”
  • Stacked modifiers: Multiple nouns or adjectives grouped together create ambiguity about relationships between words.
    • Avoid: “API endpoint configuration management system.”
    • Better: “System for managing API endpoint configuration.”
  • Prepositional phrases: Long chains of prepositional phrases (phrases starting with words like “of,” “in,” “with,” “on”) create complex sentences.
    • Avoid: “The selections of the settings in the admin panel of the application.”
    • Better: “Application settings in the admin panel.”
  • Modal auxiliary verbs: Words like “might,” “could,” “would,” and “should” that express possibility or obligation can be unclear. Use direct commands instead.
    • Avoid: “You might want to consider updating the configuration, which could potentially improve performance.”
    • Better: “Update the configuration to improve performance.”
  • Non-indicative mood: Use straightforward statements instead of subjunctive or conditional mood.
    • Avoid: “If you were to configure the settings, the application would function correctly.”
    • Better: “Configure the settings so that the application functions correctly.”
  • Invisible plurals: Make it clear whether you are referring to singular or plural items.
    • Avoid: “User data” (Could be data from one user or multiple users)
    • Better: “Data from individual users” or “Data from all users”
  • Gender-specific words: Some languages have gender rules that don’t translate directly.
    • Avoid: “When a user logs in, he should see his dashboard.”
    • Better: “After logging in, users see the dashboard.”
  • Acronyms: Define any acronyms on first use to provide context.
    • Avoid: “Use the CRUD operations.”
    • Better: “Use CRUD (Create, Read, Update, Delete) operations.”
  • Slang, jokes, or culturally specific examples: Use language that translates well.
    • Avoid: “Don’t worry, we’ve got your back.”
    • Better: “We provide support for this process.”
    • Avoid: “This feature hits it out of the park.”
    • Better: “This feature provides excellent results.”

​
Troubleshooting and FAQs