Add info on writing translatable content (#726)

* add info on making content more translatable

* Add reviewer feedback ✨

Author: ethanpalm

translations.mdx

@@ -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>
@@ -72,6 +72,57 @@ The automatic translation job doesn't handle manual changes to the localized fil
 
 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
 
 <AccordionGroup>