Source: https://developers.google.com/style/translation\n\n# Write for a global audience
Stay organized with collections
Save and categorize content based on your preferences.\n\n- Home\n- Products\n- Style\n\n\n## Page Summary\n\n- Write developer documentation in US English with localization, translation, and internationalization in mind, favoring clear and concise language for easier translation.\n- Structure content with short, unambiguous sentences, active voice, and direct address (using "you") for better comprehension across languages.\n- Maintain consistency in terminology, phrasing, formatting, and capitalization to minimize ambiguity and translation costs.\n- Prioritize inclusivity by avoiding culturally specific references, using diverse example names, and omitting colloquialisms, idioms, humor, and seasonal references.\n- Adhere to specific guidelines on grammar, word choice, and sentence structure to ensure clarity and accuracy for a global audience, referring to provided resources for detailed explanations and examples.\n\nWrite developer documentation in US English with localization, translation, and internationalization in mind, favoring clear and concise language for easier translation.\n\nStructure content with short, unambiguous sentences, active voice, and direct address (using "you") for better comprehension across languages.\n\nMaintain consistency in terminology, phrasing, formatting, and capitalization to minimize ambiguity and translation costs.\n\nPrioritize inclusivity by avoiding culturally specific references, using diverse example names, and omitting colloquialisms, idioms, humor, and seasonal references.\n\nAdhere to specific guidelines on grammar, word choice, and sentence structure to ensure clarity and accuracy for a global audience, referring to provided resources for detailed explanations and examples.\n\nWe 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.\n\nWrite with localization, translation, and
internationalization in mind. The following list defines these terms:\n\n- Localization: Adapting a product and its associated documentation for a specific country.
This process involves more than translation—for example, using local currencies or units of
measurement.\n- Translation: Translating one language to another language. This process might involve
localization, but the two terms aren't synonymous with one another.\n- Internationalization: Designing a product and its associated documentation to minimize
the localization effort—for example, placing all UI strings in a separate file to simplify
translation.\n\nFor more information, see
Language localization.\n\nFor other writing best practices, see the following resources:\n\n- Write accessible documentation\n- Write inclusive documentation\n- Voice and tone\n\n\n## Use clear, concise, and unambiguous language\n\nConsider global audiences and translation and write in a way that's clear, concise, and
unambiguous.\n\n\n### Use simpler words and shorter sentences\n\n- Use a simple word. For example, don't use words like commence when you mean start
or begin. Don't use consequently when you mean so. Don't use words like
utilize or leverage when you mean use. (It's fine to use these words when
you're conveying a special sense—for example, Cloud Spanner utilizes up to 100% of the available
CPU resources.)\n- Use a single word when it conveys the same idea as a phrase. For example, don't
use a phrase like a number of when you can use some or many.\n- Write shorter sentences. The shorter the sentence, the easier it is to translate. English sentences can be
shorter in length than some languages, so an English sentence of average length might result in a
long sentence when translated. Longer sentences can impair understanding, cause rendering issues
on the page or product interface, lengthen translation time, and increase translation and
review costs.\n\nUse a single word when it conveys the same idea as a phrase. For example, don't
use a phrase like a number of when you can use some or many.\n\n\n### Avoid phrasal verbs\n\n- Avoid phrasal verbs when possible. A phrasal verb combines multiple words to form a single
verb phrase. These verbs are also known as compound verbs. Try to substitute a simpler verb first.
There might not be a better verb; for example, a few exceptions to this rule include set up,
log in, and sign in.
Recommended: This document uses the following
terms:
Not recommended: This document makes use of
the following terms:\n\nAvoid phrasal verbs when possible. A phrasal verb combines multiple words to form a single
verb phrase. These verbs are also known as compound verbs. Try to substitute a simpler verb first.
There might not be a better verb; for example, a few exceptions to this rule include set up,
log in, and sign in.\n\nRecommended: This document uses the following
terms:\n\nNot recommended: This document makes use of
the following terms:\n\n\n### Use modifiers appropriately\n\n- Don't use too many modifiers. In particular, don't use more than two nouns as modifiers of
another noun.
Recommended: A cloud-native DevSecOps
pipeline in a hybrid environment
Not recommended: A hybrid cloud-native
DevSecOps pipeline\n- Don't misplace modifiers. For example, place a word like only immediately before the
word or phrase that it relates to. If the meaning is still ambiguous, try rephrasing the sentence.
Recommended: Request only one token.
Recommended: Request no more than one token.
Not recommended: Only request one token.\n\nDon't use too many modifiers. In particular, don't use more than two nouns as modifiers of
another noun.\n\nRecommended: A cloud-native DevSecOps
pipeline in a hybrid environment\n\nNot recommended: A hybrid cloud-native
DevSecOps pipeline\n\nDon't misplace modifiers. For example, place a word like only immediately before the
word or phrase that it relates to. If the meaning is still ambiguous, try rephrasing the sentence.\n\nRecommended: Request only one token.\n\nRecommended: Request no more than one token.\n\nNot recommended: Only request one token.\n\n\n### Use active voice and present tense\n\n- Use present tense and avoid complex or uncommon verb forms.\n- Use active voice. The subject of the sentence is the person or thing performing the action.
With passive voice, it's often hard for readers to figure out who's supposed to do something.
For more information, see Active voice.\n\n\n### Use words in their primary sense\n\n- 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 words that have multiple meanings, see the word
list entries for once, while, as, and since.\n- Avoid directional language (for example, above or below) in procedural
documentation. For more information, see
UI elements and interaction.\n\n\n### Use helper words and optional words\n\n- Use qualifying nouns for technical keywords. For example, when referring to a file called
example.yaml, call it the example.yaml file and not
example.yaml by itself. For more information, see
Grammatical treatment of code elements.\n- Repeat a word if the redundancy improves comprehension.
Recommended
Not recommended
If the VM has started and if you're able to connect...
If the VM has started and you're able to connect...
The resource hierarchy design creates both IAM segmentation and network segmentation by
default.
The resource hierarchy design creates both IAM and network segmentation by default.
An egress rule whose action is allow, whose destination is
0.0.0.0/0, and whose priority is the lowest possible (65535).
An egress rule whose action is allow, destination is 0.0.0.0/0,
and priority is the lowest possible (65535).
Use helper words. Helper words such as then, that, and of
are frequently left out of conversational English. Use these words to avoid ambiguity.
Recommended
Not recommended
If the attribute key is not found, then the default value is returned.
If the attribute key is not found, the default value is returned.
This document is intended for data engineers and assumes that you have the following
knowledge:
This document is intended for data engineers and assumes you have the following
knowledge:
Identify all of the datasets.
Identify all the datasets.
Start the profiler, and then run the app.
Start the profiler, then run the app.
See also Optional pronouns.
Don't omit relative pronouns. To provide clarity and to avoid ambiguity, use relative
pronouns such as that and which. For more information, see
Relative pronouns.
Recommended: You can programmatically update
the rules that you previously defined.
Not recommended: You can programmatically
update the rules you previously defined.\n- Use helper words. Helper words such as then, that, and of
are frequently left out of conversational English. Use these words to avoid ambiguity.
Recommended
Not recommended
If the attribute key is not found, then the default value is returned.
If the attribute key is not found, the default value is returned.
This document is intended for data engineers and assumes that you have the following
knowledge:
This document is intended for data engineers and assumes you have the following
knowledge:
Identify all of the datasets.
Identify all the datasets.
Start the profiler, and then run the app.
Start the profiler, then run the app.
See also Optional pronouns.\n- Don't omit relative pronouns. To provide clarity and to avoid ambiguity, use relative
pronouns such as that and which. For more information, see
Relative pronouns.
Recommended: You can programmatically update
the rules that you previously defined.
Not recommended: You can programmatically
update the rules you previously defined.\n\nRepeat a word if the redundancy improves comprehension.\n\n\nRecommended | Not recommended\nIf the VM has started and if you're able to connect... | If the VM has started and you're able to connect...\nThe resource hierarchy design creates both IAM segmentation and network segmentation by
default. | The resource hierarchy design creates both IAM and network segmentation by default.\nAn egress rule whose action is allow, whose destination is
0.0.0.0/0, and whose priority is the lowest possible (65535). | An egress rule whose action is allow, destination is 0.0.0.0/0,
and priority is the lowest possible (65535).\n\nUse helper words. Helper words such as then, that, and of
are frequently left out of conversational English. Use these words to avoid ambiguity.\n\n\nRecommended | Not recommended\nIf the attribute key is not found, then the default value is returned. | If the attribute key is not found, the default value is returned.\nThis document is intended for data engineers and assumes that you have the following
knowledge: | This document is intended for data engineers and assumes you have the following
knowledge:\nIdentify all of the datasets. | Identify all the datasets.\nStart the profiler, and then run the app. | Start the profiler, then run the app.\n\nSee also Optional pronouns.\n\nDon't omit relative pronouns. To provide clarity and to avoid ambiguity, use relative
pronouns such as that and which. For more information, see
Relative pronouns.\n\nRecommended: You can programmatically update
the rules that you previously defined.\n\nNot recommended: You can programmatically
update the rules you previously defined.\n\n\n### Clarify abbreviations and pronouns\n\n- Define abbreviations. Abbreviations can be confusing out of context, and they don't translate
well. Spell things out whenever possible, at least the first time that you use
a given term. For more information, see Abbreviations.\n- 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.
Recommended: If you use the term
green beer in an ad, then make sure that the ad is targeted.
Not recommended: If you use the term
green beer in an ad, then make sure that it's targeted.\n\nClarify 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.\n\nRecommended: If you use the term
green beer in an ad, then make sure that the ad is targeted.\n\nNot recommended: If you use the term
green beer in an ad, then make sure that it's targeted.\n\n\n### Use apostrophes appropriately\n\nBe careful with how you use plural and possessive forms. In general, don't form a plural with
's, don't use the plural or possessive form with trademarks of company, product, and feature
names, and don't use uncommon contractions. For more information, see Possessives, Pluralization, and Contractions.\n\n\n## Address users and their needs directly\n\nAddress the user and their needs directly and avoid providing unnecessary information.\n\n- Address the reader directly. Use you, instead of the user or they, unless
you're referring to someone who uses the software that the reader is developing. For more
information, see Second person and first person.\n- Provide context. Don't assume that the reader already knows what you're talking about.\n- Avoid negative constructions when possible. Consider whether it's necessary to tell the reader
what they can't do instead of what they can.\n\nProvide context. Don't assume that the reader already knows what you're talking about.\n\n\n## Be consistent\n\nUse standard sentence structures, consistent terminology, and appropriate punctuation to avoid
creating barriers to understanding, ambiguity, and mistranslations.\n\n\n### Use consistent terminology\n\nIf you use a particular term for a 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 might think you're referring to different concepts, and thus might use different
translations. Inconsistency in terminology and phrasing can greatly increase translation costs,
particularly when translation memory and machine translations are used as first steps in
translation.\n\n\n### Use standard sentence structures and formatting\n\n- Use standardized phrases for frequently used sentences, introductory phrases, and other common
tasks. For examples, read about introducing links,
introducing output, and
introducing code samples.\n- Use standard English word order. Sentences follow the subject + verb + object order.\n- Try to keep the main subject and verb as close to the beginning of the sentence as possible.\n- Use the conditional clause first. If you want to tell the audience to do something in a
particular circumstance, mention the circumstance before you provide the instruction. For more
information, see Sentence structure.\n- Make list items consistent. Make list items parallel in structure. Be consistent in your
capitalization and punctuation. For more information, see Lists.\n\nUse standardized phrases for frequently used sentences, introductory phrases, and other common
tasks. For examples, read about introducing links,
introducing output, and
introducing code samples.\n\n\n### Use consistent text formatting\n\n- Use consistent typographic formats. Use bold and italics consistently. Don't switch from
using italics for emphasis to underlining. For more information, see
Text-formatting summary.\n- Use consistent capitalization. For more information, see
Capitalization.\n\n\n## Be inclusive\n\nYou're not writing for your culture. Write with inclusivity in mind. For more information, see Writing inclusive documentation.\n\n- Write dates and times in unambiguous and clear ways.\n- Don't be too
culturally specific. In particular, don't refer to specific holidays, cultural practices, or sports
unless you're certain they're known worldwide.\n- 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.\n- Avoid
colloquialisms, idioms, or slang. Phrases like ballpark figure, back burner, or
hang in there can be confusing and difficult to translate.\n- Avoid humor. Most humor
is difficult to translate, and much humor is culturally specific.\n- Avoid geographically
specific references, like the seasons. Remember that August isn't summer in the southern hemisphere.
For more information, see Expressing divisions of the
year.\n\n\n## Consider accessibility for images\n\nUse screenshots and text in figures sparingly. Images don't get translated. Any new information
should be conveyed through text and not introduced in a figure or image. For more information, see
Figures and other images.\n