# Localization Friendly Writing > Reference for writing source-language strings that translate cleanly into 30+ locales. Parent: [Writing and Documentation](https://llms-explorer.com/tree/writing-and-documentation/) · 16 facets · 56 facts · page: https://llms-explorer.com/tree/localization-friendly-writing/ ## Localization-Friendly Writing - Reference for writing source-language strings that translate cleanly into 30+ locales. — [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: — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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." — [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." — [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. — [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: — [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. — [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. — [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: — [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. — [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. — [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. — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-5-placeholders-that-survive-translation) - Concatenation anti-pattern: — [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: — [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). — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-6-translator-comments) - Where does it appear? — [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: — [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 — [source](https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-7-pseudo-localization) - Replaces ASCII characters with accented Latin equivalents — [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 — [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." — [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. — [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. — [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. — [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. — [source](https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#core-concept-10-key-naming-conventions) ## References - Unicode CLDR: Plural Rules — [source](https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#references) - ICU: Formatting Messages — [source](https://llms-explorer.com/sources/mdb-context-hub/localization-friendly-writing/#references) - Mozilla L10n: Best practices for developers — [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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(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](https://llms-explorer.com/tree/localization-friendly-writing/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Context files - [Localization Friendly Writing](https://llms-explorer.com/downloads/sources/mdb-context-hub/localization-friendly-writing.md)