Localization Friendly Writing

Parent: Writing and Documentation · researched 2026-05-29T19:22:10.801Z· 8 sources · 9 concepts · skill localization-friendly-writing

Reference for writing source-language strings that translate cleanly into 30+ locales.

Localization-Friendly Writing

Reference for writing source-language strings that translate cleanly into 30+ locales. [source]

The one rule: write so a translator can reorder, expand, and replace

Every translation operation needs three freedoms: [source]
Reorder - subject-verb-object in English is not subject-verb-object in Japanese or German. [source]
Expand - German, Russian, Finnish run 30–40% longer than English. [source]
Replace - Plural forms, gendered forms, formal/informal address. [source]

Core concept 1 — The translation-friendly English rules

One sentence, one idea. Compound sentences with subordinate clauses become unparseable in OV languages. [source]
Subject-verb-object, in that order. [source]
No idioms. "Hit the ground running" has no German equivalent. [source]
No metaphors. "Move the needle" requires a needle, which requires a gauge, which requires the metaphor to land. [source]
No cultural references. No baseball, no Thanksgiving, no Marvel cinematic universe. [source]
Avoid humour and wordplay. Puns are untranslatable by definition. [source]
No abbreviations the reader must decode. "Q1," "EOY," "ASAP" - spell them out at first use. [source]
No phrasal verbs where a single verb works. "Set up the account" becomes "create the account." [source]
No latinate jargon. "Utilize" → "use." "Initiate" → "start." [source]
Active voice as the default. [source]

Core concept 2 — ICU MessageFormat: plural

Common mistake - only English plural categories: [source]
This works for English. It silently breaks Russian, Polish, Arabic. [source]

Core concept 3 — CLDR plural categories

other is required. Every plural block must include other. [source]

Core concept 4 — ICU select and selectordinal

select is a switch over a string variable, typically used for gender: [source]
other is required even in select. [source]

Core concept 5 — Placeholders that survive translation

Use named placeholders, not positional. {username} survives word reorder. %s %s does not. [source]
Never concatenate. "Hello, " + username + "!" forces English word order. [source]
Always provide a comment describing the placeholder. [source]
Concatenation anti-pattern: [source]

Core concept 6 — Translator comments

Every non-trivial string gets a translator comment answering: [source]
What is this? UI element type (button, error, tooltip, heading). [source]
What does the placeholder mean? {count} = unread messages, integer ≥ 0. [source]
Where does it appear? [source]

Core concept 7 — Pseudo-localization

Pseudo-localization is a smoke test that runs before any human translator sees the strings. It: [source]
Expands every string 30–40% to surface truncation bugs [source]
Replaces ASCII characters with accented Latin equivalents [source]
Wraps every string with sentinels like [!! … !!] to surface un-extracted strings [source]

Core concept 8 — RTL-friendly writing

Avoid baked-in directional assumptions. "Click the arrow on the right" becomes wrong in Arabic. Prefer "Click the arrow next to the search box." [source]
Numbers stay LTR inside RTL text. This is automatic in Unicode bidi. [source]

Core concept 10 — Key naming conventions

The key describes the role, not the content. [source]
Namespace by feature, then by sub-feature. [source]
Don't bury locale in the key. [source]

References

Unicode CLDR: Plural Rules [source]
ICU: Formatting Messages [source]
Mozilla L10n: Best practices for developers [source]

Children

Translation-Friendly English Rules (frontier)
ICU MessageFormat Syntax (frontier)
CLDR Plural Categories (frontier)
Named Placeholders (never positional) (frontier)
Translator Comment Discipline (frontier)
Pseudo-Localization Testing (frontier)
Avoiding Text-in-Images (frontier)
RTL-Friendly Layouts (frontier)
Key Naming Conventions (frontier)

Frontier under this node: Avoiding Text-in-Images, CLDR Plural Categories, ICU MessageFormat Syntax, Key Naming Conventions, Named Placeholders (never positional), Pseudo-Localization Testing, RTL-Friendly Layouts, Translation-Friendly English Rules, Translator Comment Discipline

← the whole tree · 3D view· how to read this page