Internationalization and Localization: Building Global Applications

# Python 3 strings are Unicode by default
text = "Hello, 世界, שָׁלוֹם"
print(len(text))  # 15 characters (not bytes!)

# Encoding to UTF-8
utf8_bytes = text.encode('utf-8')
print(len(utf8_bytes))  # 36 bytes

# Decoding back
decoded = utf8_bytes.decode('utf-8')

# FastAPI with UTF-8
from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/greeting")
def get_greeting(name: str):
    return {"message": f"Hello, {name}!"}

# Ensure UTF-8 response headers
@app.get("/greeting-unicode")
def get_greeting_unicode(name: str):
    return JSONResponse(
        {"message": f"Hello, {name}!"},
        headers={"Content-Type": "application/json; charset=utf-8"}
    )

// JavaScript: Handle Unicode properly
const greeting = "Hello, 世界!";
console.log(greeting.length); // 12 (Unicode code points)

// Spread operator handles Unicode
const chars = [...greeting];
console.log(chars); // ['H', 'e', 'l', 'l', 'o', ',', ' ', '世', '界', '!']

// Normalize Unicode for comparison
const s1 = "café";
const s2 = "café"; // with accent
console.log(s1 === s2); // false
console.log(s1.normalize("NFD") === s2.normalize("NFD")); // true

# project/locales/en/LC_MESSAGES/messages.po
# messages.pot (template file)
msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: main.py:15
msgid "Welcome to {app_name}"
msgstr "Welcome to {app_name}"

#: main.py:16
msgid "{count} items found"
msgstr ""
msgid_plural "{count} items found"
msgstr[0] "{count} item found"
msgstr[1] "{count} items found"

# messages.po (Spanish translation)
msgid "Welcome to {app_name}"
msgstr "Bienvenido a {app_name}"

msgid "{count} items found"
msgid_plural "{count} items found"
msgstr[0] "{count} elemento encontrado"
msgstr[1] "{count} elementos encontrados"

# Usage in Python
from gettext import translation
import os

# Load translations
translations_dir = os.path.join(os.path.dirname(__file__), 'locales')
t = translation('messages', localedir=translations_dir, languages=['es'])
_ = t.gettext
ngettext = t.ngettext

# Use translations
print(_("Welcome to MyApp"))  # "Bienvenido a MyApp"
print(ngettext("{count} item found", "{count} items found", 5).format(count=5))
# "5 elementos encontrados"

// i18n.js - Configuration
import i18next from 'i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';

i18next
  .use(Backend)
  .use(LanguageDetector)
  .init({
    fallbackLng: 'en',
    debug: false,
    
    interpolation: {
      escapeValue: false
    },
    
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json'
    },
    
    detection: {
      order: ['querystring', 'cookie', 'localStorage', 'navigator'],
      caches: ['localStorage', 'cookie']
    }
  });

export default i18next;

// locales/en/common.json
{
  "greeting": "Hello, {{name}}!",
  "items": {
    "one": "{{count}} item",
    "other": "{{count}} items"
  },
  "date": {
    "Today": "Today",
    "Yesterday": "Yesterday"
  },
  "cart": {
    "empty": "Your cart is empty",
    "checkout": "Proceed to checkout"
  }
}

// locales/es/common.json
{
  "greeting": "¡Hola, {{name}}!",
  "items": {
    "one": "{{count}} artículo",
    "other": "{{count}} artículos"
  },
  "date": {
    "Today": "Hoy",
    "Yesterday": "Ayer"
  },
  "cart": {
    "empty": "Tu carrito está vacío",
    "checkout": "Proceder al pago"
  }
}

// React component with translations
import { useTranslation } from 'react-i18next';

function ProductList({ products, name }) {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('greeting', { name })}</h1>
      <p>{t('items', { count: products.length })}</p>
      
      {products.length === 0 ? (
        <p>{t('cart.empty')}</p>
      ) : (
        <button>{t('cart.checkout')}</button>
      )}
    </div>
  );
}

# FastAPI: Detect locale from headers
from fastapi import Request, HTTPException
from typing import List

def get_client_locale(request: Request, supported_locales: List[str] = ['en', 'es', 'de', 'fr']) -> str:
    # Check Accept-Language header
    accept_language = request.headers.get('Accept-Language', 'en')
    
    # Parse and prioritize
    locale_weights = {}
    for part in accept_language.split(','):
        if ';' in part:
            locale, weight = part.split(';')
            locale_weights[locale.strip()] = float(weight.split('=')[1])
        else:
            locale_weights[part.strip()] = 1.0
    
    # Find best match
    for locale, weight in sorted(locale_weights.items(), key=lambda x: x[1], reverse=True):
        lang = locale.split('-')[0]  # 'en-US' -> 'en'
        if lang in supported_locales:
            return lang
    
    return 'en'

@app.get("/api/data")
def get_data(request: Request, locale: str = Depends(lambda req: get_client_locale(req))):
    return {"locale": locale, "data": get_translated_data(locale)}

// JavaScript Intl API
const formatter = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR'
});

formatter.format(1234.56); // "1.234,56 €"

// US Dollar
const usdFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

usdFormatter.format(1234.56); // "$1,234.56"

// Compact notation
const compact = new Intl.NumberFormat('en', {
  notation: 'compact',
  compactDisplay: 'short'
});

compact.format(1234567); // "1.2M"

# Python: Locale-aware formatting
from babel import Locale
from babel.numbers import format_currency, format_percent

locale = Locale('de', 'DE')

# Currency
format_currency(1234.56, 'EUR', locale=locale)  # "1.234,56 €"

# Percentages
format_percent(0.25, locale=locale)  # "25 %"

// JavaScript Intl DateTimeFormat
const date = new Date('2026-03-12T15:30:00Z');

// German format
const deFormatter = new Intl.DateTimeFormat('de-DE', {
  dateStyle: 'full',
  timeStyle: 'short'
});

deFormatter.format(date); // "Donnerstag, 12. März 2026 um 15:30"

// US format
const usFormatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'medium',
  timeStyle: 'short'
});

usFormatter.format(date); // "Mar 12, 2026, 3:30 PM"

// Relative time
const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });

rtf.format(-1, 'day');    // "yesterday"
rtf.format(3, 'week');   // "in 3 weeks"
rtf.format(-2, 'month'); // "2 months ago"

# Python: Arrow for easy datetime handling
import arrow

utc = arrow.utcnow()
print(utc.humanize())  # "2 minutes ago"

# Localize to timezone
local = utc.to('Europe/Madrid')
print(local.format('YYYY-MM-DD HH:mm'))  # "2026-03-12 16:30"

# Humanize in different locales
print(utc.to('es').humanize())  # "hace 2 minutos"

/* base.css */
[dir="ltr"] {
  --text-align: left;
  --margin-start: margin-left;
  --margin-end: margin-right;
}

[dir="rtl"] {
  --text-align: right;
  --margin-start: margin-right;
  --margin-end: margin-left;
}

/* Use logical properties */
.card {
  /* Works correctly in both directions */
  margin-inline-start: 1rem;
  padding-inline: 1rem;
  border-inline-start: 3px solid blue;
}

.icon {
  /* Flips automatically in RTL */
  transform: scaleX(-1);
}

// Detect and set direction
function setTextDirection(locale) {
  const rtlLocales = ['ar', 'he', 'fa', 'ur'];
  const isRTL = rtlLocales.includes(locale.split('-')[0]);
  
  document.documentElement.dir = isRTL ? 'rtl' : 'ltr';
  document.documentElement.lang = locale;
}

// Arabic would set dir="rtl"
setTextDirection('ar-SA'); // Sets dir="rtl"
// English would set dir="ltr"
setTextDirection('en-US'); // Sets dir="ltr"

// CLDR plural rules (i18next uses these)
const pluralRules = {
  en: (n) => n === 1 ? 'one' : 'other',  // 1 = one, 0/2+ = other
  es: (n) => n === 1 ? 'one' : 'other',   // 1 = one, rest = other
  ru: (n) => {
    if (n % 10 === 1 && n % 100 !== 11) return 'one';
    if (n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 10 || n % 100 >= 20)) return 'few';
    return 'many';
  },  // Complex Russian rules
  ar: (n) => {
    if (n === 0) return 'zero';
    if (n === 1) return 'one';
    if (n === 2) return 'two';
    if (n % 100 >= 3 && n % 100 <= 10) return 'few';
    if (n % 100 >= 11 && n % 100 <= 99) return 'many';
    return 'other';
  }  // 6 forms in Arabic
};

# Bad: Hardcoded strings
def welcome_message(name):
    return f"Welcome, {name}!"  # Can't translate

# Good: Externalized strings
def welcome_message(name, t):
    return t('welcome_message', name=name)  # Translable

# Or use a helper
from functools import partial
_ = partial(translate, locale=current_locale)

def welcome_message(name):
    return _('welcome_message', name=name)

// Bad: Using raw text as keys
const messages = {
  "Welcome": "Welcome",
  "Click here": "Click here"
};

// Good: Using semantic keys
const messages = {
  "header.welcome": "Welcome",
  "action.click_here": "Click here",
  "error.required_field": "This field is required"
};

// i18next: Handle missing translations
i18next.init({
  debug: true,  // Logs missing keys in development
  fallbackLng: 'en',
  
  // Custom fallback
  fallbackNS: 'common',
  
  // Interpolate missing values
  interpolation: {
    escapeValue: false
  }
});

// Missing key handling
t('missing.key', { defaultValue: 'Click here' });

# Jinja2 template
<p>{{ _('greeting', name=user.name) }}</p>

# Prevent injection
# Bad: "{{ name }} could contain {{ malicious content }}"
# Good: Template engines auto-escape by default
<p>{{ _('items_count', count=items|length) }}</p>

def pseudo_localize(text):
    """Convert text to pseudo-localized version for testing."""
    replacements = {
        'a': 'à', 'b': 'ƀ', 'c': 'ċ', 'd': 'đ', 'e': 'è',
        'f': 'ƒ', 'g': 'ġ', 'h': 'ħ', 'i': 'ì', 'j': 'ĵ',
        # Wrap with brackets to identify
    }
    return '[' + ''.join(replacements.get(c, c) for c in text) + ']'

# "Welcome" becomes "[Wèlċòmè]"

// Bad: Impossible to translate correctly
const msg = "Welcome " + userName + " to " + appName;

// Good: Proper interpolation
const msg = t('welcome', { userName, appName });

# Bad: Assumes English word order
# "5 results found"
message = f"{count} results found"

# Good: Allows different word orders per language
message = t('results_found', count=count)
# en: "{count} results found"
# de: "{count} Ergebnisse gefunden"
# ja: "{count}件の結果"

// Bad: Manual plural handling
const msg = count === 1 
  ? `${count} item` 
  : `${count} items`;

// Good: Built-in plural support
const msg = t('items', { count });
// en.json: { "items": "{{count}} item", "items_plural": "{{count}} items" }
// es.json: { "items": "{{count}} artículo", "items_plural": "{{count}} artículos" }

// Bad: US-centric
const date = new Date().toLocaleDateString('en-US');
const price = `$${price.toFixed(2)}`;

// Good: Locale-aware
const date = new Date().toLocaleDateString(userLocale);
const price = new Intl.NumberFormat(userLocale, {
  style: 'currency',
  currency: 'USD'
}).format(price);

// React: Load translations on demand
import { useTranslation } from 'react-i18next';
import { Suspense } from 'react';

function App() {
  const { t, i18n } = useTranslation('common');
  
  return (
    <div>
      <h1>{t('welcome')}</h1>
      <button onClick={() => i18n.changeLanguage('es')}>
        Español
      </button>
    </div>
  );
}

// Translation files loaded on first use
// common-en.json loaded initially
// common-es.json loaded when Spanish selected

# Python: Cache compiled translations
from functools import lru_cache
import translation

@lru_cache(maxsize=128)
def get_translator(locale: str):
    """Cache translators per locale."""
    return translation('messages', localedir='locales', languages=[locale])

def translate(key: str, locale: str, **kwargs):
    """Cached translation lookup."""
    translator = get_translator(locale)
    return translator.gettext(key).format(**kwargs)

# test_translations.py
import pytest
from myapp.i18n import get_translator

@pytest.mark.parametrize("locale,key,expected", [
    ('en', 'greeting', 'Hello'),
    ('es', 'greeting', 'Hola'),
    ('de', 'greeting', 'Hallo'),
])
def test_greeting_translations(locale, key, expected):
    translator = get_translator(locale)
    assert translator.gettext(key) == expected

def test_plural_forms():
    translator = get_translator('es')
    
    assert translator.ngettext('item', 'items', 1) == 'artículo'
    assert translator.ngettext('item', 'items', 2) == 'artículos'

// Playwright: Test multiple locales
import { test, expect } from '@playwright/test';

const locales = ['en', 'es', 'de', 'ar', 'ja'];

for (const locale of locales) {
  test(`Homepage renders correctly in ${locale}`, async ({ page }) => {
    await page.goto(`/?locale=${locale}`);
    
    // Check direction for RTL languages
    if (['ar', 'he', 'fa'].includes(locale)) {
      await expect(page.locator('html')).toHaveAttribute('dir', 'rtl');
    }
    
    // Verify translations loaded
    await expect(page.locator('[data-i18n="welcome"]')).toBeVisible();
  });
}