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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bonnguyenitc
• Source: bonnguyenitc/antigravity-superpowers
• License: MIT
• Homepage: https://www.npmjs.com/package/agy-superpowers

Install and usage instructions live in the source repository linked above.