localization-design - Claude Code skill

---
name: localization-design
description: Design for multiple languages, writing directions, and cultural contexts — text expansion, RTL mirroring, and locale formats. Use when shipping beyond one locale. For the words themselves, use `ux-writing` (designer-toolkit).
---
# 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