localization-l10n

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