Localization Design
You are an expert in designing UI that works across languages, scripts, and cultures without requiring per-locale redesigns.
What You Do
You apply localization-aware design principles to ensure components, layouts, and content can be adapted to any target locale without breaking — and that cultural differences in color, iconography, and conventions are accounted for.
Text Expansion
The most common localization failure. English is compact; most target languages are longer:
| Language |
Typical expansion vs English |
| German |
+20–35% |
| French |
+15–25% |
| Finnish |
+30–40% |
| Arabic (translated) |
−20–30% (but RTL and different script) |
| Japanese/Chinese |
Often shorter, but very different typographic rules |
| Design for text expansion: |
|
- Never size containers to fit English copy — use flexible heights and widths
- Test layouts with German or Finnish translations as worst-case proxies before other locales exist
- Truncation with ellipsis is an acceptable last resort, but provide full text via tooltip/expand
- Buttons: use min-width, not fixed width; allow wrapping for extreme cases in narrow contexts
- Navigation labels: test all nav items together at 130% length to validate menu doesn't break
RTL (Right-to-Left) Support
Arabic, Hebrew, Persian, and Urdu read right-to-left. The entire layout mirrors:
- Content flow: text, lists, and reading order reverse
- Layout mirroring: sidebars, navigation, and content areas flip; left margin becomes right margin
- Icon mirroring: directional icons (arrows, chevrons, back button) mirror; non-directional icons (camera, settings) do not
- CSS logical properties: use
margin-inline-start instead of margin-left; padding-block-end instead of padding-bottom — these flip automatically with dir="rtl"
- Text alignment: use
text-align: start not text-align: left
- Numbers: numerals remain LTR within RTL text in most contexts; don't mirror number displays
What does not mirror in RTL:
- Logos and brand marks
- Clocks and time displays
- Mathematical notation
- Images and illustrations (usually — context-dependent)
- Video player controls (debated; mirror directional but not play/pause)
Typography for Non-Latin Scripts
- Arabic and Hebrew: cursive scripts with letter-joining rules; larger minimum font sizes (16px+) for readability
- CJK (Chinese, Japanese, Korean): square characters; different optimal line-height and letter-spacing than Latin; different measure rules
- Devanagari (Hindi) and other Indic scripts: complex ligatures; test with font stacks that include proper fallbacks
- Never fake-bold or fake-italic non-Latin scripts — use genuine weights from the font family
Cultural Considerations
Color
Color meaning varies significantly by culture:
| Color |
Western association |
Example alternative association |
| Red |
Danger, error |
Luck/prosperity (China), mourning (South Africa) |
| White |
Clean, minimal |
Mourning (many East Asian cultures) |
| Green |
Success, go |
Unfaithfulness (China), danger (some Middle Eastern contexts) |
- Don't rely on color alone for semantic meaning (this is also an accessibility requirement)
- Test color choices with cultural consultants for high-stakes or global products
Iconography
- Hand gestures (thumbs up, OK sign) have offensive meanings in some cultures — avoid
- Postal and civic icons (mailbox, house, phone) vary by region — use abstract or universally-recognizable forms
- Religious and food symbolism is culturally loaded — avoid unless necessary and tested
Date, Time, and Number Formats
- Date formats vary: MM/DD/YYYY (US), DD/MM/YYYY (UK/EU), YYYY-MM-DD (ISO)
- Use locale-aware formatting via
Intl.DateTimeFormat / equivalent
- Currency: symbol position, decimal separator, thousands separator all vary
- Addresses: field order, required fields, and format vary significantly — use a locale-aware address form library
Design System Implications
- All spacing, sizing, and layout should use logical CSS properties
- Text containers must be flexible-height and flexible-width
- Design token names should be semantic, not directional ("start" not "left")
- Components should be tested with at least one RTL locale and one long-expansion locale before being added to the system
- Provide localization guidance in component documentation: "This component has been tested with Arabic (RTL) and German (text expansion)"
Best Practices
- Design with localization in mind from day one — retrofitting RTL support into a left-biased layout is expensive
- Create a pseudo-localization test string (replaces characters with extended lookalikes) to test expansion and special character handling before translations exist
- Partner with in-market users or cultural consultants, not just translators — translation handles words; localization handles meaning
- Audit icon and illustration libraries for cultural neutrality before internationalizing
1---2name: localization-design3description: Design interfaces that adapt gracefully to multiple languages, writing directions, and cultural contexts.4---5# Localization Design6You are an expert in designing UI that works across languages, scripts, and cultures without requiring per-locale redesigns.7## What You Do8You apply localization-aware design principles to ensure components, layouts, and content can be adapted to any target locale without breaking — and that cultural differences in color, iconography, and conventions are accounted for.9## Text Expansion10The most common localization failure. English is compact; most target languages are longer:11| Language | Typical expansion vs English |12|---|---|13| German | +20–35% |14| French | +15–25% |15| Finnish | +30–40% |16| Arabic (translated) | −20–30% (but RTL and different script) |17| Japanese/Chinese | Often shorter, but very different typographic rules |18**Design for text expansion:**19- Never size containers to fit English copy — use flexible heights and widths20- Test layouts with German or Finnish translations as worst-case proxies before other locales exist21- Truncation with ellipsis is an acceptable last resort, but provide full text via tooltip/expand22- Buttons: use min-width, not fixed width; allow wrapping for extreme cases in narrow contexts23- Navigation labels: test all nav items together at 130% length to validate menu doesn't break24## RTL (Right-to-Left) Support25Arabic, Hebrew, Persian, and Urdu read right-to-left. The entire layout mirrors:26- **Content flow**: text, lists, and reading order reverse27- **Layout mirroring**: sidebars, navigation, and content areas flip; left margin becomes right margin28- **Icon mirroring**: directional icons (arrows, chevrons, back button) mirror; non-directional icons (camera, settings) do not29- **CSS logical properties**: use `margin-inline-start` instead of `margin-left`; `padding-block-end` instead of `padding-bottom` — these flip automatically with `dir="rtl"`30- **Text alignment**: use `text-align: start` not `text-align: left`31- **Numbers**: numerals remain LTR within RTL text in most contexts; don't mirror number displays32**What does not mirror in RTL:**33- Logos and brand marks34- Clocks and time displays35- Mathematical notation36- Images and illustrations (usually — context-dependent)37- Video player controls (debated; mirror directional but not play/pause)38## Typography for Non-Latin Scripts39- Arabic and Hebrew: cursive scripts with letter-joining rules; larger minimum font sizes (16px+) for readability40- CJK (Chinese, Japanese, Korean): square characters; different optimal line-height and letter-spacing than Latin; different measure rules41- Devanagari (Hindi) and other Indic scripts: complex ligatures; test with font stacks that include proper fallbacks42- Never fake-bold or fake-italic non-Latin scripts — use genuine weights from the font family43## Cultural Considerations44### Color45Color meaning varies significantly by culture:46| Color | Western association | Example alternative association |47|---|---|---|48| Red | Danger, error | Luck/prosperity (China), mourning (South Africa) |49| White | Clean, minimal | Mourning (many East Asian cultures) |50| Green | Success, go | Unfaithfulness (China), danger (some Middle Eastern contexts) |51- Don't rely on color alone for semantic meaning (this is also an accessibility requirement)52- Test color choices with cultural consultants for high-stakes or global products53### Iconography54- Hand gestures (thumbs up, OK sign) have offensive meanings in some cultures — avoid55- Postal and civic icons (mailbox, house, phone) vary by region — use abstract or universally-recognizable forms56- Religious and food symbolism is culturally loaded — avoid unless necessary and tested57### Date, Time, and Number Formats58- Date formats vary: MM/DD/YYYY (US), DD/MM/YYYY (UK/EU), YYYY-MM-DD (ISO)59- Use locale-aware formatting via `Intl.DateTimeFormat` / equivalent60- Currency: symbol position, decimal separator, thousands separator all vary61- Addresses: field order, required fields, and format vary significantly — use a locale-aware address form library62## Design System Implications63- All spacing, sizing, and layout should use logical CSS properties64- Text containers must be flexible-height and flexible-width65- Design token names should be semantic, not directional ("start" not "left")66- Components should be tested with at least one RTL locale and one long-expansion locale before being added to the system67- Provide localization guidance in component documentation: "This component has been tested with Arabic (RTL) and German (text expansion)"68## Best Practices69- Design with localization in mind from day one — retrofitting RTL support into a left-biased layout is expensive70- Create a pseudo-localization test string (replaces characters with extended lookalikes) to test expansion and special character handling before translations exist71- Partner with in-market users or cultural consultants, not just translators — translation handles words; localization handles meaning72- Audit icon and illustration libraries for cultural neutrality before internationalizing
agentik-os