Skip to content

Add info on writing translatable content #726

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.

Sign up for GitHub

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 2 commits into from
May 23, 2025
Merged

Add info on writing translatable content #726

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
32f5d8d
add info on making content more translatable
ethanpalm May 23, 2025
92febaf
Add reviewer feedback ✨
ethanpalm May 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 54 additions & 3 deletions translations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Translations
description: Automatically translate your documentation with AI.
icon: 'languages'
title: "Translations"
description: "Automatically translate your documentation with AI"
icon: "languages"
---

<Info>
Expand Down Expand Up @@ -72,6 +72,57 @@

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**: Active voice makes your instructions more clear and translatable.
* **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.

Check warning on line 96 in translations.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

translations.mdx#L96 

Did you really mean 'Nominalizations'?
* **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

<AccordionGroup>
Expand Down