Internationalization (i18n)

Core Principles

• Write concise, technical TypeScript code with accurate examples
• Use functional and declarative programming patterns; avoid classes
• Ensure all user-facing text is internationalized and supports localization
• Use descriptive variable names with auxiliary verbs (isLoading, hasError)
• Design for text expansion (some languages require 30-50% more space)

Web Application i18n

React/Next.js Applications

• Use i18next and react-i18next for web applications
• Implement namespace-based translation organization
• Use interpolation for dynamic values in translations
• Leverage pluralization features for count-based text
• Implement context-based translations where needed

Implementation Pattern

// Use translation hooks
const { t } = useTranslation('common');

// Basic translation
<h1>{t('welcome.title')}</h1>

// With interpolation
<p>{t('greeting', { name: userName })}</p>

// With pluralization
<span>{t('items', { count: itemCount })}</span>

Nuxt.js Applications

• Use @nuxtjs/i18n module for Vue applications
• Implement SEO best practices with localized routes
• Use

  useI18n

  composable for translations
• Leverage lazy loading for translation files

React Native/Expo Applications

Mobile i18n Setup

• Use expo-localization for React Native apps
• Use react-native-i18n or i18n-js for translations
• Detect device locale automatically
• Support fallback languages

Mobile-Specific Considerations

• Support RTL (right-to-left) layouts
• Ensure proper text scaling for accessibility
• Handle device locale changes dynamically
• Test on devices with different system languages

Translation File Organization

File Structure

locales/
  en/
    common.json
    auth.json
    errors.json
  es/
    common.json
    auth.json
    errors.json
  fr/
    common.json
    auth.json
    errors.json

Translation Keys Best Practices

• Use descriptive, hierarchical keys (e.g.,

  auth.login.button

  ,

  errors.network.timeout

  )
• Avoid embedding HTML in translations when possible
• Keep translations context-aware and meaningful
• Document translation context for translators

Locale-Aware Formatting

Date and Time

• Use Intl.DateTimeFormat for date formatting
• Respect user's locale preferences
• Store dates in UTC, display in local timezone
• Support multiple date format preferences

Numbers and Currency

• Use Intl.NumberFormat for number formatting
• Display currency in user's preferred format
• Handle decimal and thousand separators by locale
• Support right-to-left number display where needed

Sorting and Comparison

• Use Intl.Collator for locale-aware string comparison
• Implement locale-specific sorting rules
• Handle diacritics and special characters correctly

RTL (Right-to-Left) Support

Layout Considerations

• Use CSS logical properties (margin-inline-start, padding-inline-end)
• Implement bidirectional text support
• Mirror UI layouts for RTL languages
• Test thoroughly with RTL languages (Arabic, Hebrew, etc.)

Implementation

/* Use logical properties */
.element {
  margin-inline-start: 1rem;
  padding-inline-end: 0.5rem;
}

Best Practices

Development Guidelines

• Never hardcode user-facing strings
• Extract all text to translation files
• Use ICU message format for complex translations
• Implement fallback mechanisms for missing translations
• Support language switching without page reload

Content Considerations

• Avoid text in images; use CSS/SVG text when possible
• Design flexible layouts that accommodate text expansion
• Use icons with text labels, not icons alone
• Consider cultural differences in imagery and color

Testing Requirements

• Test with pseudolocalization during development
• Verify text doesn't overflow containers
• Test with actual translations before release
• Verify RTL layout with native speakers
• Test currency and date formats across locales

State Management for i18n

Storing User Preferences

• Use Zustand or React Context for language state
• Persist language preference (localStorage, AsyncStorage)
• Sync language preference with user account
• Handle server-side rendering with correct locale

Data Fetching

• Use TanStack React Query for caching translated content
• Invalidate queries on language change when needed
• Fetch locale-specific content from APIs
• Handle translation loading states gracefully

Error Handling

• Provide translated error messages
• Implement fallback to default language for missing translations
• Log missing translation keys in development
• Handle RTL/LTR text direction in error displays
• Use Zod for runtime validation with localized error messages