-
Notifications
You must be signed in to change notification settings - Fork 207
Automated translations docs #717
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 10 commits
Commits
Show all changes
15 commits
Select commit
Hold shift + click to select a range
3b9a8b5
translations page v0
IHSten d941f48
fix broken link
IHSten 214c901
Update `icon`
ethanpalm 0184a5f
overview edits
ethanpalm 72a4955
revise prerequisites
ethanpalm 06d1b7f
update getting started
ethanpalm 4247ddb
Update ongoing translations section
ethanpalm 6feef5c
update troubleshooting and FAQs
ethanpalm f72a0e9
delete extra line
ethanpalm ef7ea26
copy edits
ethanpalm 06f06b1
Add link in languages section of Navigation
ethanpalm 863ca94
add Han feedback
ethanpalm af9235c
add Lucas feedback
ethanpalm 1070b7f
add screenshot
ethanpalm 4e6bc99
wrap image in frame
ethanpalm File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ethanpalm marked this conversation as resolved.
Show resolved
Hide resolved
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
ethanpalm marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
ethanpalm marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
ethanpalm marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
Mintlify will never automatically publish translations to production. You must review and merge each translation pull request before the changes are live. | ||
ethanpalm marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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> | ||
ethanpalm marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.