diff --git a/docs.json b/docs.json index e0ab9a57e..48fd62d7e 100644 --- a/docs.json +++ b/docs.json @@ -114,6 +114,7 @@ "settings/preview-deployments", "settings/custom-scripts", "mcp", + "translations", { "group": "Integrations", "icon": "blocks", diff --git a/images/translations/translations-dashboard-dark.png b/images/translations/translations-dashboard-dark.png new file mode 100644 index 000000000..887e7e185 Binary files /dev/null and b/images/translations/translations-dashboard-dark.png differ diff --git a/images/translations/translations-dashboard-light.png b/images/translations/translations-dashboard-light.png new file mode 100644 index 000000000..211474b1f Binary files /dev/null and b/images/translations/translations-dashboard-light.png differ diff --git a/navigation.mdx b/navigation.mdx index dfd2e2908..f0ef6dacb 100644 --- a/navigation.mdx +++ b/navigation.mdx @@ -295,6 +295,10 @@ Versions can be leveraged to partition your navigation into different versions. Languages can be leveraged to partition your navigation into different languages. + + You can automate [translations](/translations) of your documentation into any supported language. + + + 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](/navigation#languages) feature, allowing readers to switch between available languages in your documentation. + + + Translations dashboard in light mode + + Translations dashboard in dark 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](https://dashboard.mintlify.com/settings/organization/translations). + +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](/navigation#languages) 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](mailto:support@mintlify.com). + + + + 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](/navigation#languages) feature. + + If the language you'd like to translate to is not listed, please [contact support](mailto:support@mintlify.com) 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. + +