|
| 1 | +--- |
| 2 | +title: Translations |
| 3 | +description: Automatically translate your documentation with AI. |
| 4 | +icon: 'languages' |
| 5 | +--- |
| 6 | + |
| 7 | +<Info> |
| 8 | + Automated translations are available as a paid add-on to Growth, Pro, and Enterprise plans. Please{" "} |
| 9 | + < a href="mailto:[email protected]">contact sales</ a> for more information. |
| 10 | +</Info> |
| 11 | + |
| 12 | +## Overview |
| 13 | + |
| 14 | +You can automatically translate your documentation into multiple languages while maintaining structure, formatting, and links with AI. Translations integrate with the [languages](/navigation#languages) feature, allowing readers to switch between available languages in your documentation. |
| 15 | + |
| 16 | +<Frame> |
| 17 | + <img |
| 18 | + className="block dark:hidden my-0 pointer-events-none" |
| 19 | + src="/images/translations/translations-dashboard-light.png" |
| 20 | + alt="Translations dashboard in light mode" |
| 21 | + /> |
| 22 | + |
| 23 | + <img |
| 24 | + className="hidden dark:block my-0 pointer-events-none" |
| 25 | + src="/images/translations/translations-dashboard-dark.png" |
| 26 | + alt="Translations dashboard in dark mode" |
| 27 | + /> |
| 28 | +</Frame> |
| 29 | + |
| 30 | +## Prerequisites |
| 31 | + |
| 32 | +- You must have a Growth, Pro, or Enterprise plan and translation add-ons for your target languages. |
| 33 | +- You must use GitHub as your repository provider for your documentation content. |
| 34 | +- Your documentation must use English as a base language. |
| 35 | +- You must have a valid `docs.json` file in your repository. |
| 36 | +- All content to be translated must use valid `MDX` formatting. Any invalid `MDX` will cause the translation to fail. |
| 37 | + |
| 38 | +## Getting Started |
| 39 | + |
| 40 | +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. |
| 41 | + |
| 42 | +You can initiate a complete translation from the translations page in your [dashboard](https://dashboard.mintlify.com/settings/organization/translations). |
| 43 | + |
| 44 | +1. Select **Start translation**. |
| 45 | +2. Select the first language that you want to translate your content to and then select **Start translation**. |
| 46 | +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. |
| 47 | +4. Review the pull request and merge it. |
| 48 | +5. Repeat the process for each language that you want to translate to. |
| 49 | + |
| 50 | +<Info> |
| 51 | + An automated translation is stored under a directory named after the [language code](/navigation#languages) that you have selected. |
| 52 | + |
| 53 | + Custom directory names for translations are not supported at this time. |
| 54 | +</Info> |
| 55 | + |
| 56 | +## Ongoing Translations |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +The ongoing translation process follows this sequence: |
| 61 | + |
| 62 | +1. A member of your organization makes changes to the documentation in your repository. |
| 63 | +2. When the changes are pushed or merged into your main branch, the ongoing translation job is triggered. |
| 64 | +3. The translation job updates, removes, or creates the required files in all subscribed languages based on your `docs.json` file. |
| 65 | +4. The translation job creates a separate branch and pull request containing the translated changes for your review. |
| 66 | + |
| 67 | +<Info> |
| 68 | +Mintlify will never automatically publish translations to production. You must review and merge each translation pull request before the changes are live. |
| 69 | +</Info> |
| 70 | + |
| 71 | +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. |
| 72 | + |
| 73 | +We recommend promptly reviewing and merging translation pull requests so that your localizations are kept in sync. |
| 74 | + |
| 75 | +## Troubleshooting and FAQs |
| 76 | + |
| 77 | +<AccordionGroup> |
| 78 | + <Accordion title="What content is translated?"> |
| 79 | + The translation service translates all non-code, non-component content in your documentation. This includes: |
| 80 | + |
| 81 | + - Text |
| 82 | + - Links |
| 83 | + - Titles and descriptions in frontmatter |
| 84 | + - Component attributes |
| 85 | + - Navigation labels |
| 86 | + |
| 87 | + The service does not translate: |
| 88 | + |
| 89 | + - Code blocks |
| 90 | + - Images or other media |
| 91 | + - Metadata |
| 92 | + </Accordion> |
| 93 | + |
| 94 | + <Accordion title="How do I update my translations manually?"> |
| 95 | + If you need to modify your translations, make any changes directly in the translation pull requests created by the translation service. |
| 96 | + |
| 97 | + Any manual changes may be overwritten the next time the English version of the page is updated and the translation job runs. |
| 98 | + </Accordion> |
| 99 | + |
| 100 | + <Accordion title="Why isn't my translation working?"> |
| 101 | + Check these common issues: |
| 102 | + - Verify that your translation subscription is active for the language. |
| 103 | + - Confirm that your content uses valid `MDX` formatting. |
| 104 | + - Confirm that your `docs.json` file is properly configured. |
| 105 | + |
| 106 | + If you're still running into problems, please [contact support ](mailto:[email protected]). |
| 107 | + </Accordion> |
| 108 | + |
| 109 | + <Accordion title="Why do translation PRs sometimes include unchanged sections?"> |
| 110 | + The translation system operates at the page level, and will attempt to translate entire pages when any portion changes. |
| 111 | + |
| 112 | + This approach ensures that the translation is as accurate as possible and removes the need for manual updates to localized files. |
| 113 | + </Accordion> |
| 114 | + |
| 115 | + <Accordion title="My desired language isn't available."> |
| 116 | + We offer translations for all languages supported by the [languages](/navigation#languages) feature. |
| 117 | + |
| 118 | + If the language you'd like to translate to is not listed, please [contact support ](mailto:[email protected]) and we'll be happy to assist. |
| 119 | + </Accordion> |
| 120 | + |
| 121 | + <Accordion title="Can I define specific translations for words or prevent terms from being translated?"> |
| 122 | + The translation service does not support custom translation rules for specific terms or phrases. We are developing this feature for a future release. |
| 123 | + </Accordion> |
| 124 | +</AccordionGroup> |
0 commit comments