Documentation is not only translated — it is read by people with different cultural backgrounds, assumptions, and expectations. Content that feels neutral or obvious to one audience may be confusing, inappropriate, or offensive to another. This article covers the cultural dimensions of global writing beyond literal translation, and is a direct companion to the Writing for Translation and Localization guide — read that one for sentence-level and machine-translation guidance, and this one for the cultural judgment calls that sit alongside it.
Avoid Culturally Loaded Metaphors and Examples
Many common examples in English-language documentation rely on cultural familiarity that does not transfer globally. When choosing examples, scenarios, and analogies, use situations that are universally relatable. See the Idioms and Culture-Bound Language section of the Common Voice and Tone Mistakes guide and the Culturally Neutral Language section of the Writing Bias-Free Content guide for the base rule on idioms; the table below extends that same principle to examples and scenarios specifically.
| Potentially problematic | More universal alternative |
|---|---|
| Thanksgiving planning example | Event or project planning example |
| Baseball scoring analogy | A points or scoring analogy from a clearly described context |
| References to specific national holidays | "At the end of a reporting period" or "during a company event" |
| Dollar amounts in examples | Use a generic currency symbol (e.g., "100 units of currency") or explicitly label: "$100 USD" — see the Currency section of the Numbers, Dates, and Time guide for the full formatting rule. |
Names and Personal Examples
When using example names in documentation (for user accounts, form fields, sample data), choose names that represent diverse cultural backgrounds rather than defaulting to a narrow set. Avoid names that may be difficult to read or recall for most of your audience. See the Bias in Example Content section of the Writing Bias-Free Content guide for the fuller treatment of this, including assumed family structures and imagery.
Good practice is to use clearly fictional or generic placeholders: "User A," "user@example.com," or generic names like "Alex" and "Jordan" that work across many languages. If you need culturally specific examples, note the locale explicitly.
Address and Contact Information Formats
Address formats, phone number formats, and postal codes vary significantly by country. Do not assume a specific format when giving instructions about contact fields in a UI.
- Describe fields generically: "Enter your postal code or ZIP code."
- Do not hardcode example phone numbers with a specific country code unless demonstrating a locale-specific feature.
- In screenshots and examples, use clearly fictional data: "555-0100" or "XX XXX" rather than a real format from one country.
Color Symbolism
Color carries different cultural meanings. Red means "stop" or "danger" in many Western contexts, but "good luck" and "prosperity" in others. Green does not universally mean "safe" or "approved."
When writing documentation that references UI colors — for example, "the green indicator means the integration is active" — describe the meaning, not just the color: "The green indicator (labeled Active) confirms the integration is running." This is the same underlying rule as the "don't rely on color alone" requirement in the Colors and Highlighting section of the Formatting Standards guide, applied here specifically to cross-cultural interpretation rather than accessibility — the fix is identical either way.
Icons and Imagery
Beyond color, icons and imagery can carry unintended meaning across cultures — a hand gesture, a symbol, or an image that reads as harmless or friendly in one culture can be confusing or offensive in another. When choosing icons for documentation (beyond standard, near-universal UI icons like a gear for settings or a magnifying glass for search), favor well-established, widely recognized symbols over illustrative or gesture-based imagery, and if in doubt, ask someone familiar with the target locale before publishing.
Humor and Informal Tone
Humor is culturally specific and does not translate well. What reads as friendly and approachable to one audience may seem flippant, confusing, or disrespectful to another. In globally distributed documentation, err toward clarity and a consistently professional tone over attempts at humor.
This does not mean the writing must be formal or cold. Warmth comes from directness, respect for the reader's time, and clarity — not from jokes or colloquial asides.
Reading Direction and Layout (RTL)
Arabic, Hebrew, Persian, and Urdu are written right-to-left (RTL). See the Right-to-Left (RTL) Languages section of the Writing for Translation and Localization guide for the full treatment of mirrored screenshots, layout adaptation, and directional references. As a quick summary: avoid all directional language ("the button on the left") in favor of element names and labels, since positional references break the moment a layout mirrors for an RTL audience.
Sensitivity Across Geographies
Some topics are sensitive in specific regions and may require localization review beyond translation. These include:
- Political references, maps, or regional boundaries.
- References to specific governments, legal systems, or regulations that vary by jurisdiction.
- Religious or cultural observances.
- Social norms around formality — some languages and cultures expect formal address ("vous" vs. "tu" in French) where English uses a single "you."
When writing content that will be deployed in regions with known sensitivities, flag it for local review before publishing.
Formality Levels
English has one second-person pronoun: "you." Many other languages distinguish between formal and informal address. When your content is translated, translators must make a choice about formality level that the English source does not specify.
Establish a formality guideline in your project's localization brief so translators aren't left to guess, and provide that same instruction in any style guide you give to human translators or AI translation tools. If your organization has standardized on a specific formality level for translated documentation, that standard should be documented in your platform-specific translation policy rather than assumed.
Self-Audit Checklist
Before publishing globally distributed content, check the article against these questions:
- Do examples use universally recognizable scenarios, not culturally specific ones (national holidays, region-specific sports, single-currency assumptions)?
- Are sample names diverse and broadly readable, rather than defaulting to a narrow set?
- Are address, phone number, and postal code fields described generically rather than assuming one country's format?
- Do color references include a label or description, not just the color name?
- Are icons and imagery checked for unintended cultural meaning beyond standard, universally recognized symbols?
- Is the content free of humor, jokes, or culturally specific asides?
- Is the article free of directional language, consistent with the RTL guidance in Writing for Translation and Localization?
- Has any politically, legally, religiously, or otherwise regionally sensitive content been flagged for local review?
- Has a formality-level instruction been provided to translators or translation tools, rather than left unspecified?