Design and implement internationalization (i18n) — RTL layout, text expansion budgeting, locale-aware APIs, cultural color semantics, pseudo-localization testing, and Vietnamese-specific considerations. Use when asked about "RTL", "right-to-left", "internationalization", "localization", "i18n", "l10n", "translate the app", "text expansion", "Arabic/Hebrew layout", or "support multiple languages". Do NOT use for: translation content itself — that is a human/MT workflow. Do NOT use for: font loading — use `typography-system`.
Instrucciones de origen · Vista previa de solo lectura
name
i18n-patterns
description
Design and implement internationalization (i18n) — RTL layout, text expansion budgeting, locale-aware APIs, cultural color semantics, pseudo-localization testing, and Vietnamese-specific considerations. Use when asked about "RTL", "right-to-left", "internationalization", "localization", "i18n", "l10n", "translate the app", "text expansion", "Arabic/Hebrew layout", or "support multiple languages". Do NOT use for: translation content itself — that is a human/MT workflow. Do NOT use for: font loading — use `typography-system`.
Any web frontend. CSS logical properties + Intl API. React/Vue/Svelte examples included.
When to Use
Use when: adding a second language to any UI
Use when: Arabic, Hebrew, Persian, or Urdu support is required (RTL)
Use when: UI breaks with German/Finnish/Vietnamese text (text expansion)
Use when: date, number, or currency formatting is hardcoded
Use when: running pre-ship i18n audit
Do NOT use for: translation management workflows — that is ops/tooling
RTL (Right-to-Left) Layout
Never use physical directions in CSS — use logical properties
/* ❌ Physical — breaks in RTL */margin-left: 16px;
padding-right: 8px;
border-left: 2px solid;
text-align: left;
float: left;
/* ✓ Logical — works in both LTR and RTL */margin-inline-start: 16px;
padding-inline-end: 8px;
border-inline-start: 2px solid;
text-align: start;
float: inline-start;
Enable RTL on the root element
<htmllang="ar"dir="rtl"><!-- OR for dynamic switching: --><htmllang="ar"dir="auto">
/* Flexbox is RTL-aware when dir is set */.nav { display: flex; gap: 8px; }
/* In RTL: items flow right→left automatically *//* CSS logical shorthands */.card {
margin-block: 16px; /* top + bottom */margin-inline: 24px; /* start + end (left in LTR, right in RTL) */padding-block: 12px;
padding-inline: 16px;
}
Icons and directional assets
Arrows, back buttons, chevrons: flip horizontally in RTL
Non-directional icons (star, heart, warning): do NOT flip
Technique: transform: scaleX(-1) scoped to [dir="rtl"]
"1 item" vs "2 items" (complex in Arabic: 6 plural forms)
Intl.Collator
Locale-correct alphabetical sorting
Cultural Color Semantics
Color meaning varies by culture. Never assume universal mapping.
Color
Western
East Asian
Middle East
Red
Danger, error
Luck, success
Caution
Green
Success, go
Envy (some contexts)
Islam, safety
White
Purity, clean
Mourning (some)
Purity
Purple
Royalty, luxury
Mourning (some)
Royalty
Yellow
Warning
Imperial, sacred
Mixed
Rules:
Never convey information through color alone — add icon or text label
For error/success states: always use shape + color (not color-only)
Run a cultural review for any product entering a new major market
Vietnamese-Specific Notes
/* Vietnamese text benefits from more line height — diacritics stack vertically */:lang(vi) {
line-height: 1.7;
word-spacing: 0.05em; /* words are monosyllabic, slight gap aids reading */
}
/* Vietnamese uses Latin script — no special font required *//* But: ensure font includes full Vietnamese Unicode range (U+0300–U+036F, U+1E00–U+1EFF) */
Date format: dd/MM/yyyy or ngày dd tháng MM năm yyyy
Comma is decimal separator in some Vietnamese conventions — use Intl.NumberFormat consistently
Plural forms: Vietnamese has no grammatical plural — "1 mục" and "5 mục" use the same form
Pseudo-Localization Testing
Run pseudo-localization before any real translation. Catches layout issues early.
// Simple pseudo-localizer — wrap ASCII chars in diacritics + add lengthfunctionpseudoLocalize(str) {
const map = { a:'à', e:'è', i:'ì', o:'ò', u:'ù', n:'ñ' };
return'[' + str.replace(/[aeioún]/g, c => map[c] || c) + ' ~~~]';
}
// "Sign In" → "[Sìgñ Ìñ ~~~]"// The brackets expose missing overflow handling// The ~~~ adds +30% length to simulate German expansion
Run pseudo-localization across all UI strings before handing off to translators.
Any layout that breaks with pseudo-localized strings will break with real translations.
Pre-Ship i18n Checklist
□ All user-visible strings externalized to message catalog (no hardcoded English)
□ Dates: using Intl.DateTimeFormat — no manual format strings
□ Numbers/currency: using Intl.NumberFormat
□ Plural forms: Intl.PluralRules used (or i18n library handles it)
□ RTL layout: CSS logical properties throughout, tested with dir="rtl"
□ Directional icons: flip rules defined for RTL
□ Text expansion: tested with German (+35%) — no overflow/truncation issues
□ Pseudo-localization: run across all screens — no layout breaks
□ Color semantics: no information conveyed by color alone
□ Font: tested with all target scripts (Latin, Arabic, CJK as applicable)
Anti-Fake-Pass Rules
Before claiming i18n is done, you MUST show:
All strings externalized — no hardcoded English in templates
Dates and numbers using Intl API (not manual formatting)
RTL tested: at least one screen rendered with dir="rtl" screenshot/evidence
Text expansion: UI tested with German or Finnish strings (+35%)
Pseudo-localization run: no layout breaks reported
