Automated translations docs

docs.json

@@ -114,6 +114,7 @@
               "settings/preview-deployments",
               "settings/custom-scripts",
               "mcp",
+              "translations",
               {
                 "group": "Integrations",
                 "icon": "blocks",

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.
 
+<Info>
+  You can automate [translations](/translations) of your documentation into any supported language.
+</Info>
+
 <img
   className="block dark:hidden pointer-events-none"
   src="/images/navigation/languages-light.png"

translations.mdx

@@ -0,0 +1,124 @@
+---
+title: Translations
+description: Automatically translate your documentation with AI.
+icon: 'languages'
+---
+
+<Info>
+  Automated translations are available as a paid add-on to Growth, Pro, and Enterprise plans. Please{" "}
+  <a href="mailto:[email protected]">contact sales</a> for more information.
+</Info>
+
+## 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.
+
+<Frame>
+  <img
+    className="block dark:hidden my-0 pointer-events-none"
+    src="/images/translations/translations-dashboard-light.png"
+    alt="Translations dashboard in light mode"
+  />
+
+  <img
+    className="hidden dark:block my-0 pointer-events-none"
+    src="/images/translations/translations-dashboard-dark.png"
+    alt="Translations dashboard in dark mode"
+  />
+</Frame>
+
+## 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.
+
+<Info>
+  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.
+</Info>
+
+## 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.
+
+<Info>
+Mintlify will never automatically publish translations to production. You must review and merge each translation pull request before the changes are live.
+</Info>
+
+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
+
+<AccordionGroup>
+  <Accordion title="What content is translated?">
+    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
+  </Accordion>
+
+  <Accordion title="How do I update my translations manually?">
+    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.
+  </Accordion>
+
+  <Accordion title="Why isn't my translation working?">
+    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:[email protected]).
+  </Accordion>
+
+  <Accordion title="Why do translation PRs sometimes include unchanged sections?">
+    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.
+  </Accordion>
+
+  <Accordion title="My desired language isn't available.">
+    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:[email protected]) and we'll be happy to assist.
+  </Accordion>
+
+  <Accordion title="Can I define specific translations for words or prevent terms from being translated?">
+    The translation service does not support custom translation rules for specific terms or phrases. We are developing this feature for a future release.
+  </Accordion>
+</AccordionGroup>