Automated translations docs

docs.json

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

translations.mdx

@@ -0,0 +1,106 @@
+---
+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.
+
+## 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 pull request with their changes is merged, 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. For each subscribed language, 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
+
+<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>