diff --git a/docs.json b/docs.json index 9f5bd19f2..8c54e1cea 100644 --- a/docs.json +++ b/docs.json @@ -112,7 +112,6 @@ "mcp", "guides/claude-code", "guides/cursor", - "translations", "react-components", "settings/custom-scripts", "settings/seo", diff --git a/navigation.mdx b/navigation.mdx index 26c95d5fb..e1b0c7632 100644 --- a/navigation.mdx +++ b/navigation.mdx @@ -304,10 +304,6 @@ 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](https://mintlify.com/pricing). - - -## 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). - -1. Select **Translations** in the left sidebar. -1. Select **Configure**. -2. Select the languages that you want to translate your content to and then select **Save configuration**. -3. The translation process will create a new branch and pull request in your docs repository with the translated content. Larger documentation sets may take longer to process. -4. Review the pull request and merge it. - - - 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. - -## 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 - - - - 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](/contact-support). - - - - 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. - - - - The translation service does not support custom translation rules for specific terms or phrases. We are developing this feature for a future release. - - \ No newline at end of file