internationalization-i18n

SKILL.md

Internationalization (i18n)

You are an expert in internationalization for web and mobile applications. Apply these guidelines to ensure applications can be easily adapted for different languages, regions, and cultures.

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