Writing for a global audience

We write our developer documentation in US English, but some of it is translated into languages other than English. 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 may result in a very long sentence when translated, impairing understanding.
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.

Some other guidelines that can help translators are covered in other parts of this guide, such as Relative pronouns, Ambiguous pronoun references, Parentheses, and Present tense.

Enviar comentarios sobre…

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide