Localization Friendly Writing
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill writing-expert/references/localization-friendly-writing.md
↓ Facts as markdownall context files
Reference for writing source-language strings that translate cleanly into 30+ locales.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Localization-Friendly Writing
- Reference for writing source-language strings that translate cleanly into 30+ locales. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#localization-friendly-writing]
The one rule: write so a translator can reorder, expand, and replace
- Every translation operation needs three freedoms: [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#the-one-rule-write-so-a-translator-can-reorder-expand-and-replace]
- Reorder - subject-verb-object in English is not subject-verb-object in Japanese or German. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#the-one-rule-write-so-a-translator-can-reorder-expand-and-replace]
- Expand - German, Russian, Finnish run 30–40% longer than English. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#the-one-rule-write-so-a-translator-can-reorder-expand-and-replace]
- Replace - Plural forms, gendered forms, formal/informal address. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#the-one-rule-write-so-a-translator-can-reorder-expand-and-replace]
Core concept 1 — The translation-friendly English rules
- One sentence, one idea. Compound sentences with subordinate clauses become unparseable in OV languages. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- Subject-verb-object, in that order. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- No idioms. "Hit the ground running" has no German equivalent. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- No metaphors. "Move the needle" requires a needle, which requires a gauge, which requires the metaphor to land. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- No cultural references. No baseball, no Thanksgiving, no Marvel cinematic universe. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- Avoid humour and wordplay. Puns are untranslatable by definition. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- No abbreviations the reader must decode. "Q1," "EOY," "ASAP" - spell them out at first use. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- No phrasal verbs where a single verb works. "Set up the account" becomes "create the account." [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- No latinate jargon. "Utilize" → "use." "Initiate" → "start." [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
- Active voice as the default. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-1-the-translation-friendly-english-rules]
Core concept 2 — ICU MessageFormat: plural
- Common mistake - only English plural categories: [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-2-icu-messageformat-plural]
- This works for English. It silently breaks Russian, Polish, Arabic. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-2-icu-messageformat-plural]
Core concept 3 — CLDR plural categories
- other is required. Every plural block must include other. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-3-cldr-plural-categories]
Core concept 4 — ICU select and selectordinal
- select is a switch over a string variable, typically used for gender: [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-4-icu-select-and-selectordinal]
- other is required even in select. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-4-icu-select-and-selectordinal]
Core concept 5 — Placeholders that survive translation
- Use named placeholders, not positional. {username} survives word reorder. %s %s does not. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-5-placeholders-that-survive-translation]
- Never concatenate. "Hello, " + username + "!" forces English word order. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-5-placeholders-that-survive-translation]
- Always provide a comment describing the placeholder. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-5-placeholders-that-survive-translation]
Core concept 6 — Translator comments
- Every non-trivial string gets a translator comment answering: [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-6-translator-comments]
- What is this? UI element type (button, error, tooltip, heading). [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-6-translator-comments]
- What does the placeholder mean? {count} = unread messages, integer ≥ 0. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-6-translator-comments]
- Where does it appear? [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-6-translator-comments]
Core concept 7 — Pseudo-localization
- Pseudo-localization is a smoke test that runs before any human translator sees the strings. It: [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-7-pseudo-localization]
- Expands every string 30–40% to surface truncation bugs [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-7-pseudo-localization]
- Replaces ASCII characters with accented Latin equivalents [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-7-pseudo-localization]
- Wraps every string with sentinels like [!! … !!] to surface un-extracted strings [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-7-pseudo-localization]
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." [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-8-rtl-friendly-writing]
- Numbers stay LTR inside RTL text. This is automatic in Unicode bidi. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-8-rtl-friendly-writing]
Core concept 10 — Key naming conventions
- The key describes the role, not the content. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-10-key-naming-conventions]
- Namespace by feature, then by sub-feature. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-10-key-naming-conventions]
- Don't bury locale in the key. [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-10-key-naming-conventions]
References
- Unicode CLDR: Plural Rules [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#references]
- ICU: Formatting Messages [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#references]
- Mozilla L10n: Best practices for developers [archived source: https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#references]
Where this helps
- Writing UI strings, error messages, or notification copy for a product shipping in 30+ locales, where a literal translation of an English idiom or metaphor would be meaningless or wrong. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Designing a pluralization or gendered-form message — counts, "items remaining," selectable pronouns — that must work correctly across languages with different plural-category systems than English's two. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Building a UI that needs to support right-to-left languages, where directional phrasing like "the arrow on the right" silently becomes incorrect once translated. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Preparing source strings for professional translation, where translator comments and named placeholders are the difference between a fast, accurate translation pass and a slow, error-prone one. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Rewrite compound, subordinate-clause-heavy sentences into one-sentence-one-idea, subject-verb-object form before sending strings to translation. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Replace every idiom, metaphor, and cultural reference in UI copy with plain, literal language that doesn't depend on a shared cultural frame. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Structure every pluralized or gendered string with ICU MessageFormat's `select`/`selectordinal`, always including the required `other` category. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Run pseudo-localization on a build before it reaches human translators, to catch truncation, un-extracted strings, and hardcoded concatenation early. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Concatenating strings around a variable ("Hello, " + username + "!") instead of using a named placeholder — this bakes in English word order and breaks in languages with different sentence structure. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Using positional placeholders (%s %s) instead of named ones ({username}) — positional placeholders don't survive the word reordering translation requires. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Handling plurals with only English's two categories (one/other) instead of the full CLDR set, which silently produces grammatically wrong output in Russian, Polish, or Arabic. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Baking directional assumptions ("click the arrow on the right") into UI copy instead of describing the element by what it is, breaking the instruction once the UI mirrors for RTL. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- German, Russian, and Finnish translations commonly run 30–40% longer than the English source, so UI layouts sized to the English string will truncate or wrap unexpectedly once translated. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Pseudo-localization catches expansion and un-extracted-string bugs before human translation, but it is a smoke test, not a substitute for a real linguistic review by native speakers. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- `other` is a required CLDR plural/select category even in languages like English where it functions as the default catch-all — omitting it breaks the ICU MessageFormat contract even if English output looks fine. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Translator comments only help if someone actually writes them for every non-trivial string; a placeholder like {count} is ambiguous to a translator without a comment stating what it means and its expected range. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
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