We write our developer documentation in US English, but some of it is translated into languages other than English or is read by developers for whom English is not their primary language. Write with translation in mind.
A few specific recommendations:
- Write short, clear sentences.
The shorter the sentence, the easier it is to translate. English is shorter than most languages; an average length English sentence might result in a very long sentence when translated, impairing understanding.
- Write dates and times in unambiguous and clear ways.
- Be consistent.
- For example, if you use a particular term for a particular concept in one place, then use that exact same term elsewhere, including the same capitalization. If you use different names for the same thing, translators may think you're referring to different concepts, and thus may use different translations.
- Also, don't use the same word to mean different things. In particular, avoid using the same word as both a noun and a verb in close proximity. For examples of the multiple-meanings issue, see the word list entries for once and since.
- Avoid abbreviations.
- Abbreviations can be confusing out of context, and they don't translate well. Spell things out whenever possible, at least the first time you use a given term.
- Don't use too many modifiers.
- In particular, don't use more than two nouns as modifiers of another noun.
- Avoid misplaced modifiers.
- For example, place a word like "only" or "just" immediately before the noun or verb it relates to.
- Not recommended: Developers only need to apply for one token.
- Recommended: Developers need to apply for only one token.
- Clarify antecedents.
- Using pronouns can get tricky when translators are working with small, unconnected strings of text. Help them out by making things as clear as possible. For example, if a pronoun is ambiguous, then replace it with the appropriate noun.
- Not recommended: If you use the term "green beer" in an ad, then make sure it's targeted.
- Recommended: If you use the term "green beer" in an ad, then make sure the ad is targeted.
- Don't be too culturally specific.
- In particular, don't refer to specific holidays, cultural practices, sports, etc., unless you're certain they're known worldwide.
- Also avoid colloquialisms. Phrases like "ballpark figure," "back burner," or "hang in there" can be confusing.
- Use a diverse set of example names
- If you need to use people's names (for example, as email addresses), use a diverse set of names. For more information, see Example domains and names.