Localization (l10n)
You are an expert in localization for web and mobile applications. Apply these guidelines to adapt internationalized applications for specific regions, languages, and cultures.
Core Principles
- Localization (l10n) builds on internationalization (i18n)
- Ensure all user-facing text supports localization
- Adapt content for cultural appropriateness
- Respect regional conventions for dates, numbers, and currency
- Design for content that varies significantly between locales
Localization Libraries
Web Applications
- Use i18next and react-i18next for web applications
- Implement namespace-based translation organization
- Use libraries like react-intl or next-i18next for Next.js applications
- Leverage formatjs for ICU message format support
Mobile Applications
- Use expo-localization for React Native apps
- Use react-native-i18n or expo-localization for internationalization and localization
- Support multiple languages with fallback mechanisms
- Handle device locale detection automatically
Translation Management
File Organization
locales/
en-US/
common.json
legal.json
marketing.json
en-GB/
common.json
legal.json
marketing.json
es-ES/
common.json
legal.json
marketing.json
es-MX/
common.json
legal.json
marketing.json
Regional Variants
- Support regional language variants (en-US vs en-GB, es-ES vs es-MX)
- Implement fallback chains (es-MX -> es -> en)
- Handle spelling differences (color vs colour)
- Adapt terminology for regional preferences
Locale-Specific Formatting
Date and Time Formatting
// Format dates according to locale
const formatDate = (date: Date, locale: string) => {
return new Intl.DateTimeFormat(locale, {
year: 'numeric',
month: 'long',
day: 'numeric'
}).format(date);
};
// US: January 23, 2026
// UK: 23 January 2026
// Germany: 23. Januar 2026
Number Formatting
// Format numbers according to locale
const formatNumber = (num: number, locale: string) => {
return new Intl.NumberFormat(locale).format(num);
};
// US: 1,234,567.89
// Germany: 1.234.567,89
// France: 1 234 567,89
Currency Formatting
// Format currency according to locale
const formatCurrency = (amount: number, locale: string, currency: string) => {
return new Intl.NumberFormat(locale, {
style: 'currency',
currency: currency
}).format(amount);
};
// US/USD: $1,234.56
// Germany/EUR: 1.234,56 EUR
// Japan/JPY: JPY 1,235
Cultural Adaptation
Content Localization
- Adapt imagery for cultural appropriateness
- Localize marketing content, not just translate
- Consider cultural sensitivities in color choices
- Adapt examples and references for local relevance
Legal and Compliance
- Localize privacy policies and terms of service
- Adapt for regional legal requirements (GDPR, CCPA)
- Display appropriate regulatory information
- Handle region-specific disclaimers
Layout and Typography
Text Expansion
- Design for 30-50% text expansion from English
- Use flexible layouts that accommodate longer text
- Test with German (often longest) and Chinese (often shortest)
- Avoid fixed-width containers for text
RTL Support
- Implement full RTL (right-to-left) support for Arabic, Hebrew, etc.
- Use CSS logical properties for directional layouts
- Mirror UI elements appropriately
- Handle bidirectional text (mixed LTR/RTL)
/* Use logical properties for RTL support */
.card {
margin-inline-start: 1rem;
padding-inline-end: 0.5rem;
text-align: start;
}
Typography Considerations
- Use fonts that support required character sets
- Consider CJK (Chinese, Japanese, Korean) typography needs
- Support Arabic and other script-specific requirements
- Implement proper line breaking for different languages
Regional Features
Address Formats
- Adapt address forms for regional formats
- Support international phone number formats
- Handle postal/ZIP code validation by country
- Implement country-specific form validation
Measurement Units
- Support metric and imperial units
- Display appropriate units based on locale
- Allow user preference override
- Convert values accurately
Calendars and Time
- Support different calendar systems (Gregorian, Hijri, etc.)
- Handle timezone display preferences
- Support different week start days (Sunday vs Monday)
- Display appropriate date formats
Testing and Quality Assurance
Localization Testing
- Test with native speakers for each locale
- Verify layout with actual translated content
- Test all date, number, and currency formats
- Verify RTL layouts function correctly
Automated Checks
- Implement missing translation detection
- Check for hardcoded strings in code
- Validate translation file format and completeness
- Monitor for translation quality issues
Pseudolocalization
- Use pseudolocalization during development
- Detect hardcoded strings early
- Verify UI handles text expansion
- Test character encoding support
Content Delivery
Language Detection
- Detect user language from browser/device settings
- Support URL-based locale switching (/en/, /es/, /fr/)
- Persist user language preference
- Implement graceful fallback mechanisms
Performance Optimization
- Lazy load translation files by namespace
- Cache translations appropriately
- Use CDN for static translation files
- Minimize initial translation bundle size
Integration Best Practices
State Management
- Store locale preference in user settings
- Sync preference across devices when logged in
- Handle locale changes without full page reload
- Update all components on locale switch
API Integration
- Pass locale in API requests
- Return localized content from backend when appropriate
- Handle server-side locale negotiation
- Support content negotiation headers
