# I18N Localization

> Use when planning internationalization (i18n) architecture, localizing an app for new markets, managing translations, or optimizing for non-English app store listings

- Skill: `bonnguyenitc/i18n-localization` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bonnguyenitc/i18n-localization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bonnguyenitc/i18n-localization/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: bonnguyenitc (https://skillmd.com/u/bonnguyenitc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bonnguyenitc/i18n-localization

---


# 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:**
- [ ] Hardcoded strings in UI code
- [ ] String concatenation for user-visible sentences
- [ ] Manual date/number formatting (not using `Intl.*` or locale library)

**Should fix:**
- [ ] App Store listing not localized for top 3 download markets
- [ ] Layout uses `left`/`right` instead of `start`/`end` (RTL-incompatible)
- [ ] No pseudo-localization test (catches text overflow and layout issues before real translation)

---

## Who to Pair With
- `app-store-optimizer` — for App Store listing localization strategy
- `mobile-developer` — for React Native / Flutter i18n implementation
- `frontend-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