i18n / Localization Lens
Philosophy: Localization is not translation. It's redesigning the experience for a different culture.
A poorly localized app signals "we don't really care about your market."
Core Instincts
- i18n first, l10n second — build the architecture for internationalization before translating
- Never hardcode strings — every user-visible string lives in an external translation file
- RTL is a layout problem, not a text problem — Hebrew, Arabic require mirrored layouts
- Local market ≠ translated market — date formats, numbers, currencies, cultural norms all differ
- App Store localization = free ASO — localized store listings rank in local search without app changes
i18n vs l10n
| Term |
Definition |
| i18n (internationalization) |
Engineering — building support for multiple locales |
| l10n (localization) |
Content — adapting content for a specific locale |
| t9n (translation) |
Linguistic — converting text between languages |
Technical Requirements
Strings
- Never concatenate user-visible strings:
"Hello " + name → use named placeholders: "Hello {name}"
- Pluralization rules differ by language (Russian has 4 plural forms; English has 2)
- Use ICU message format for complex strings:
{count, plural, one {# item} other {# items}}
Date / Time / Numbers
| Category |
Example variance |
| Date format |
US: 12/31/2024, EU: 31/12/2024, ISO: 2024-12-31 |
| Time format |
12h (US) vs 24h (EU/Asia) |
| Number format |
1,234.56 (US) vs 1.234,56 (EU) vs 1 234,56 (FR) |
| Currency |
Symbol position varies; decimal precision varies by currency |
| Calendar |
Gregorian default; some markets use Islamic, Hebrew, Chinese calendars |
Always use: Intl.DateTimeFormat, Intl.NumberFormat (JS) or locale-aware libraries — never manually format.
Right-to-Left (RTL) Languages
Arabic, Hebrew, Persian, Urdu — require:
- Mirrored layout (left → right becomes right → left)
- Text alignment:
start / end instead of left / right
- Icons that indicate direction must be flipped
- Test with: RTL pseudo-localization before translating
App Store Localization Priority
Localize store listings first — no code changes needed, immediate revenue impact.
| Market |
Language |
Potential uplift |
| China |
Simplified Chinese |
🔴 High (largest iOS market) |
| Japan |
Japanese |
🔴 High (highest ARPU per user) |
| Germany |
German |
🟠 Medium-high |
| Brazil |
Portuguese (BR) |
🟠 Medium-high |
| France |
French |
🟡 Medium |
| South Korea |
Korean |
🟡 Medium |
Rule: Localize App Store listing → measure download increase → justify full app localization.
❌ Anti-Patterns to Avoid
| ❌ NEVER DO |
Why |
✅ DO INSTEAD |
| Hardcode strings in UI components |
Impossible to translate in future |
All strings in i18n/en.json from day one |
| Use string concatenation for sentences |
Word order differs by language |
Named placeholders in translation keys |
| Assume text length = English length |
German is ~35% longer; Chinese is ~50% shorter |
Design UI for 150% of English text length |
| Use machine translation (Google Translate) for store listing |
Quality signals carelessness |
Professional translation for app store copy |
| Translate only UI — not error messages, emails, notifications |
Inconsistent experience |
All user-visible text in translation files |
| Design with only LTR in mind |
RTL markets are large (Arabic = 400M speakers) |
Use logical CSS properties (inset-inline-start) from start |
Questions You Always Ask
When architecting i18n:
- Are all strings externalized into translation files (zero hardcoded UI text)?
- Does the date/number/currency formatting use locale-aware APIs?
- Is the layout system using logical properties (
start/end) for RTL readiness?
When planning a new market:
- What's the current revenue from that country without localization?
- What's the expected uplift from App Store listing localization vs full app localization?
- Are there cultural norms that affect UX? (e.g., messaging apps are primary in some markets)
Red Flags
Must fix:
Should fix:
Who to Pair With
app-store-optimizer — for App Store listing localization strategymobile-developer — for React Native / Flutter i18n implementationfrontend-developer — for web i18n and RTL CSS
Tools
React: react-i18next / next-intl · Flutter: flutter_localizations + ARB files · iOS native: NSLocalizedString + .xcstrings · Translation management: Lokalise · Phrase · Crowdin · Quality: Pseudo-localization testing → Appium
1---2name: i18n-localization3description: Use when planning internationalization (i18n) architecture, localizing an app for new markets, managing translations, or optimizing for non-English app store listings4---56# i18n / Localization Lens78> **Philosophy:** Localization is not translation. It's redesigning the experience for a different culture.9> A poorly localized app signals "we don't really care about your market."1011---1213## Core Instincts1415- **i18n first, l10n second** — build the architecture for internationalization before translating16- **Never hardcode strings** — every user-visible string lives in an external translation file17- **RTL is a layout problem, not a text problem** — Hebrew, Arabic require mirrored layouts18- **Local market ≠ translated market** — date formats, numbers, currencies, cultural norms all differ19- **App Store localization = free ASO** — localized store listings rank in local search without app changes2021---2223## i18n vs l10n2425| Term | Definition |26|------|-----------|27| **i18n** (internationalization) | Engineering — building support for multiple locales |28| **l10n** (localization) | Content — adapting content for a specific locale |29| **t9n** (translation) | Linguistic — converting text between languages |3031---3233## Technical Requirements3435### Strings36- Never concatenate user-visible strings: `"Hello " + name` → use named placeholders: `"Hello {name}"`37- Pluralization rules differ by language (Russian has 4 plural forms; English has 2)38- Use ICU message format for complex strings: `{count, plural, one {# item} other {# items}}`3940### Date / Time / Numbers41| Category | Example variance |42|----------|-----------------|43| Date format | US: 12/31/2024, EU: 31/12/2024, ISO: 2024-12-31 |44| Time format | 12h (US) vs 24h (EU/Asia) |45| Number format | 1,234.56 (US) vs 1.234,56 (EU) vs 1 234,56 (FR) |46| Currency | Symbol position varies; decimal precision varies by currency |47| Calendar | Gregorian default; some markets use Islamic, Hebrew, Chinese calendars |4849**Always use:** `Intl.DateTimeFormat`, `Intl.NumberFormat` (JS) or locale-aware libraries — never manually format.5051### Right-to-Left (RTL) Languages52Arabic, Hebrew, Persian, Urdu — require:53- Mirrored layout (left → right becomes right → left)54- Text alignment: `start` / `end` instead of `left` / `right`55- Icons that indicate direction must be flipped56- Test with: RTL pseudo-localization before translating5758---5960## App Store Localization Priority6162Localize store listings first — no code changes needed, immediate revenue impact.6364| Market | Language | Potential uplift |65|--------|----------|-----------------|66| China | Simplified Chinese | 🔴 High (largest iOS market) |67| Japan | Japanese | 🔴 High (highest ARPU per user) |68| Germany | German | 🟠 Medium-high |69| Brazil | Portuguese (BR) | 🟠 Medium-high |70| France | French | 🟡 Medium |71| South Korea | Korean | 🟡 Medium |7273**Rule:** Localize App Store listing → measure download increase → justify full app localization.7475---7677## ❌ Anti-Patterns to Avoid7879| ❌ NEVER DO | Why | ✅ DO INSTEAD |80|------------|-----|--------------|81| Hardcode strings in UI components | Impossible to translate in future | All strings in `i18n/en.json` from day one |82| Use string concatenation for sentences | Word order differs by language | Named placeholders in translation keys |83| Assume text length = English length | German is ~35% longer; Chinese is ~50% shorter | Design UI for 150% of English text length |84| Use machine translation (Google Translate) for store listing | Quality signals carelessness | Professional translation for app store copy |85| Translate only UI — not error messages, emails, notifications | Inconsistent experience | All user-visible text in translation files |86| Design with only LTR in mind | RTL markets are large (Arabic = 400M speakers) | Use logical CSS properties (`inset-inline-start`) from start |8788---8990## Questions You Always Ask9192**When architecting i18n:**93- Are all strings externalized into translation files (zero hardcoded UI text)?94- Does the date/number/currency formatting use locale-aware APIs?95- Is the layout system using logical properties (`start`/`end`) for RTL readiness?9697**When planning a new market:**98- What's the current revenue from that country without localization?99- What's the expected uplift from App Store listing localization vs full app localization?100- Are there cultural norms that affect UX? (e.g., messaging apps are primary in some markets)101102---103104## Red Flags105106**Must fix:**107- [ ] Hardcoded strings in UI code108- [ ] String concatenation for user-visible sentences109- [ ] Manual date/number formatting (not using `Intl.*` or locale library)110111**Should fix:**112- [ ] App Store listing not localized for top 3 download markets113- [ ] Layout uses `left`/`right` instead of `start`/`end` (RTL-incompatible)114- [ ] No pseudo-localization test (catches text overflow and layout issues before real translation)115116---117118## Who to Pair With119- `app-store-optimizer` — for App Store listing localization strategy120- `mobile-developer` — for React Native / Flutter i18n implementation121- `frontend-developer` — for web i18n and RTL CSS122123---124125## Tools126**React:** `react-i18next` / `next-intl` · **Flutter:** `flutter_localizations` + ARB files · **iOS native:** `NSLocalizedString` + `.xcstrings` · **Translation management:** Lokalise · Phrase · Crowdin · **Quality:** Pseudo-localization testing → Appium
bonnguyenitc