// locale-manager.ts
import IntlMessageFormat from 'intl-messageformat';
import { Platform } from 'react-native'; // or use environment-specific storage

interface LocaleBundle {
  [key: string]: string;
}

interface LocaleConfig {
  defaultLocale: string;
  supportedLocales: string[];
  cacheKey: string;
  storage: {
    getItem: (key: string) => Promise<string | null>;
    setItem: (key: string, value: string) => Promise<void>;
  };
}

export class LocaleManager {
  private bundles: Record<string, LocaleBundle> = {};
  private currentLocale: string;
  private formatters: Record<string, IntlMessageFormat> = {};

  constructor(private config: LocaleConfig) {
    this.currentLocale = config.defaultLocale;
  }

  async init() {
    // Load cached bundle for current locale
    const cached = await this.config.storage.getItem(this.config.cacheKey);
    if (cached) {
      this.bundles[this.currentLocale] = JSON.parse(cached);
    } else {
      await thi

s.loadLocale(this.currentLocale); } }

async loadLocale(locale: string): Promise<void> { if (this.bundles[locale]) return;

// In production, fetch from CDN or bundle split
const response = await fetch(`/locales/${locale}.json`);
if (!response.ok) throw new Error(`Locale ${locale} not found`);

const bundle: LocaleBundle = await response.json();
this.bundles[locale] = bundle;
await this.config.storage.setItem(this.config.cacheKey, JSON.stringify(bundle));

}

async switchLocale(locale: string): Promise<void> { if (!this.config.supportedLocales.includes(locale)) { throw new Error(Locale ${locale} not supported); }

if (!this.bundles[locale]) {
  await this.loadLocale(locale);
}

this.currentLocale = locale;
this.formatters = {}; // Clear cached formatters
Platform.OS === 'ios' ? this.updateiOSLocale(locale) : this.updateAndroidLocale(locale);

}

t(key: string, values?: Record<string, any>): string { const bundle = this.bundles[this.currentLocale]; if (!bundle?.[key]) { console.warn(Missing key: ${key} in ${this.currentLocale}); return key; }

if (!this.formatters[key]) {
  this.formatters[key] = new IntlMessageFormat(bundle[key], this.currentLocale);
}

return this.formatters[key].format(values) as string;

}

formatNumber(value: number, options?: Intl.NumberFormatOptions): string { return new Intl.NumberFormat(this.currentLocale, options).format(value); }

formatDate(date: Date, options?: Intl.DateTimeFormatOptions): string { return new Intl.DateTimeFormat(this.currentLocale, options).format(date); }

getDirection(): 'ltr' | 'rtl' { const rtlLocales = ['ar', 'he', 'fa', 'ur']; return rtlLocales.includes(this.currentLocale.split('-')[0]) ? 'rtl' : 'ltr'; }

private async updateiOSLocale(locale: string) { // Bridge to native locale override if required // iOS requires app restart for full system locale sync }

private async updateAndroidLocale(locale: string) { // Bridge to native locale override // Android supports runtime locale switching via Activity recreation } }

### Architecture Decisions and Rationale

- **Semantic keys over content-as-keys**: Using `welcome_message` instead of `"Welcome"` prevents translation drift and enables safe refactoring. Content-as-keys break when source text changes.
- **Lazy loading with persistent cache**: Shipping all locales upfront wastes bandwidth and storage. Lazy loading fetches only the active locale, caching it locally. Subsequent launches load from cache in <15ms.
- **Formatter caching**: `IntlMessageFormat` compilation is CPU-intensive. Caching compiled formatters per key eliminates repeated parsing during UI renders.
- **Build-time validation over runtime fallbacks**: Runtime fallbacks mask missing keys and degrade UX silently. Build-time schema checks fail fast, enforce ICU syntax, and guarantee parity across locales.
- **Platform bridge for locale switching**: iOS and Android handle locale changes differently. iOS requires app restart for full system sync; Android supports runtime Activity recreation. The manager abstracts this via platform-specific bridges while keeping the JS layer consistent.
- **RTL logical properties**: Hardcoded `margin-left` breaks in Arabic/Hebrew. Using `margin-inline-start` or framework-agnostic RTL mirroring ensures layout consistency without duplicating components.

## Pitfall Guide

1. **Hardcoding strings in components**  
   Embedding `"Submit"` directly in UI code prevents extraction, blocks TMS integration, and forces manual search-and-replace during updates. Extract all strings to semantic keys before development begins.

2. **Ignoring ICU pluralization and gender rules**  
   English has two plural forms; Russian has four; Arabic has six. Using simple `if/else` logic breaks grammar. ICU `plural` and `select` rules handle language-specific morphology automatically.

3. **Assuming 1:1 string length**  
   German compounds can be 2x longer than English. Chinese is typically 30% shorter. Fixed-width containers overflow or leave excessive whitespace. Use dynamic layout constraints, `flexWrap`, and overflow truncation with ellipsis.

4. **Missing RTL mirroring**  
   Icons, padding, and flex directions must flip. Left-aligned text becomes right-aligned. Carousels reverse swipe direction. Implement a layout mirroring utility that applies `flexDirection: 'row-reverse'` and swaps margin/padding based on `getDirection()`.

5. **Shipping all locales in the initial bundle**  
   Bundling 50 languages adds 15–30MB to the APK/IPA. Users download what they don't need. Split locale assets into remote chunks or use dynamic feature modules (Android) / on-demand resources (iOS).

6. **No build-time validation**  
   Missing keys, duplicate entries, and malformed ICU syntax reach production. Implement a pre-commit or CI validation script that compares key sets across all locales, checks ICU syntax compliance, and fails the build on mismatch.

7. **Neglecting app store metadata localization**  
   The app store listing is the first touchpoint. Unlocalized screenshots, descriptions, and keywords reduce conversion by 40–60% in target markets. Localize metadata alongside the app bundle.

**Best practices from production:**  
- Use a schema validator (JSON Schema or Zod) to enforce structure before TMS upload.  
- Automate screenshot testing per locale to catch layout breaks early.  
- Implement a fallback chain: active locale → default locale → key name. Never crash on missing translation.  
- Version locale bundles. Cache invalidation prevents stale translations after hotfixes.  
- Monitor localization-specific metrics: key coverage %, runtime switch success rate, and TMS sync latency.

## Production Bundle

### Action Checklist
- [ ] Extract all UI strings to semantic keys with ICU syntax before development
- [ ] Configure build-time validation to enforce key parity and ICU compliance
- [ ] Implement lazy-loaded locale provider with persistent cache
- [ ] Integrate `IntlMessageFormat` and native `Intl` APIs for formatting
- [ ] Add RTL layout mirroring utility for flex, padding, and icon direction
- [ ] Split locale assets into remote chunks or dynamic modules
- [ ] Connect CI/CD pipeline to TMS for automated key extraction and pull
- [ ] Implement locale switch handler with platform-specific bridges

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| <10 languages, static content | Client-side JSON with eager loading | Simplicity outweighs optimization needs | Low (initial bundle +5–8%) |
| 10–30 languages, dynamic UI | Lazy-loaded provider + CDN chunks | Balances performance and scalability | Medium (CDN hosting + build pipeline) |
| 30+ languages, enterprise scale | Server-driven locale delivery + A/B testing | Enables real-time updates, regional targeting, and performance monitoring | High (TMS integration, infra, monitoring) |
| Cross-platform (RN/Flutter) | Shared TypeScript core + platform bridges | Prevents duplication, ensures consistent ICU behavior | Medium (bridge development, testing matrix) |

### Configuration Template

```json
// locales/schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "patternProperties": {
    "^[a-zA-Z0-9_]+$": {
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": false
}

// i18n.config.ts
import { LocaleManager } from './locale-manager';
import AsyncStorage from '@react-native-async-storage/async-storage';

export const localeManager = new LocaleManager({
  defaultLocale: 'en',
  supportedLocales: ['en', 'es', 'fr', 'de', 'ar', 'ja', 'zh'],
  cacheKey: '@locale_bundle',
  storage: {
    getItem: (key) => AsyncStorage.getItem(key),
    setItem: (key, value) => AsyncStorage.setItem(key, value),
  },
});

// Build-time validation script (run via CI)
// 1. Load all locale JSON files
// 2. Compare key sets using deep equality
// 3. Validate ICU syntax with `intl-messageformat-parser`
// 4. Exit 1 on mismatch or syntax error

Quick Start Guide

1. Initialize the manager: Import LocaleManager, configure supported locales, and attach persistent storage.
2. Extract strings: Replace inline text with localeManager.t('key'). Use ICU syntax for variables: t('greeting', { name: user }).
3. Add build validation: Run a pre-commit hook that checks key parity across locales/*.json and validates ICU syntax. Fail the build on mismatch.
4. Enable lazy loading: Call localeManager.init() on app start. Switch locales via localeManager.switchLocale('es') and render UI conditionally based on getDirection().
5. Connect TMS: Export en.json to Lokalis/Crowdin. Configure CI to pull translated files, run validation, and trigger bundle generation. Deploy locale chunks to CDN.

Localization scales when treated as infrastructure, not content. The architecture above eliminates runtime crashes, reduces bundle footprint, enforces grammatical correctness, and integrates cleanly into modern CI/CD pipelines. Implement it before UI development begins, and the localization layer will pay for itself in retention, review scores, and engineering velocity.