Localization & i18n 🌍

<?php
// i18n vs l10n — two words you'll hear constantly:
//   i18n (internationalization) = making your code CAPABLE of many languages
//                                 (no hardcoded text, placeholders, plural slots)
//   l10n (localization)         = the actual translations + locale formatting
//
// The golden rule: NEVER hardcode user-facing text. Look it up by a KEY instead.

class Translator
{
    /** @var array<string, array<string,string>>  locale => (key => text) */
    private array $messages = [];

    public function __construct(
        private string $locale,          // the language we're showing now
        private string $fallback = 'en', // used when a key is missing
    ) {}

    // Load one language's message file (here just an array).
    public function load(string $locale, array $messages): void
    {
        $this->messages[$locale] = $messages;
    }

    public function setLocale(string $locale): void
    {
        $this->locale = $locale;
    }

    // Look up $key for the current locale; fall back to English, then the key.
    // Replace :placeholders (e.g. :name) with the values you pass in.
    public function t(string $key, array $params = []): string
    {
        $msg = $this->messages[$this->locale][$key]
            ?? $this->messages[$this->fallback][$key]   // ?? = "use this if null"
            ?? $key;                                     // last resort: show the key

        foreach ($params as $name => $value) {
            $msg = str_replace(":{$name}", (string) $value, $msg);
        }
        return $msg;
    }
}

$trans = new Translator('en');

$trans->load('en', [
    'welcome'  => 'Welcome to our store!',
    'greeting' => 'Hello, :name!',
    'checkout' => 'Proceed to Checkout',
]);
$trans->load('es', [
    'welcome'  => '¡Bienvenido a nuestra tienda!',
    'greeting' => '¡Hola, :name!',
    'checkout' => 'Proceder al pago',
]);

foreach (['en', 'es'] as $locale) {
    $trans->setLocale($locale);
    echo "[{$locale}]\n";
    echo "  " . $trans->t('welcome') . "\n";              // no placeholder
    echo "  " . $trans->t('greeting', ['name' => 'Alice']) . "\n"; // :name -> Alice
    echo "  " . $trans->t('checkout') . "\n";
}

[en]
  Welcome to our store!
  Hello, Alice!
  Proceed to Checkout
[es]
  ¡Bienvenido a nuestra tienda!
  ¡Hola, Alice!
  Proceder al pago

<?php
// setlocale() changes how PHP's BUILT-IN functions behave for a category:
//   LC_MONETARY  -> money,  LC_TIME -> dates,  LC_ALL -> everything.
// It depends on locales being installed on the server, so prefer intl
// (next section) for real formatting. This shows the classic approach.

// gettext is the GNU translation standard. You wrap text in _() and ship
// compiled .mo files per language. The pattern (not run here) looks like:
//
//   setlocale(LC_MESSAGES, 'es_ES.UTF-8');
//   bindtextdomain('messages', __DIR__ . '/locale');
//   textdomain('messages');
//   echo _('Welcome');         // -> "Bienvenido" if es_ES is installed
//   echo ngettext('1 file', '%d files', $n);  // gettext picks the plural form

// Whichever system you use, ALWAYS declare UTF-8 so accents survive:
header('Content-Type: text/html; charset=UTF-8');         // for web pages
mb_internal_encoding('UTF-8');                            // multibyte string ops

$word = 'Crème brûlée';
echo $word . "\n";
echo "strlen (bytes):   " . strlen($word) . "\n";       // counts BYTES
echo "mb_strlen (chars): " . mb_strlen($word) . "\n";   // counts CHARACTERS

Crème brûlée
strlen (bytes):   13
mb_strlen (chars): 12

<?php
// PHP's intl extension wraps ICU — the same Unicode library Chrome and Java use.
// It formats numbers, currency, dates and percents using each locale's REAL rules.

$amount = 1234567.89;
$date   = new DateTimeImmutable('2025-03-15 14:30', new DateTimeZone('UTC'));

$locales = [
    'en-US' => 'USD',   // United States dollars
    'de-DE' => 'EUR',   // German euros
    'ja-JP' => 'JPY',   // Japanese yen (no decimal places)
];

foreach ($locales as $locale => $currency) {
    // CURRENCY: pass the ISO code; the formatter adds the right symbol & decimals.
    $cur  = new NumberFormatter($locale, NumberFormatter::CURRENCY);
    // PERCENT: 0.1547 becomes "15%" / "15 %" depending on locale.
    $pct  = new NumberFormatter($locale, NumberFormatter::PERCENT);
    // DATES: LONG date, with the visitor's time zone applied.
    $df   = new IntlDateFormatter(
        $locale,
        IntlDateFormatter::LONG,   // e.g. "March 15, 2025"
        IntlDateFormatter::SHORT,  // time part, e.g. "2:30 PM"
        'Europe/Paris'             // convert the UTC time into this zone
    );

    echo "[{$locale}]\n";
    echo "  currency: " . $cur->formatCurrency($amount, $currency) . "\n";
    echo "  percent:  " . $pct->format(0.1547)                     . "\n";
    echo "  date:     " . $df->format($date)                       . "\n";
}

// === Detect the visitor's locale (best-to-worst priority) ===
function detectLocale(): string {
    if (isset($_GET['lang']))    return $_GET['lang'];      // ?lang=fr
    if (isset($_COOKIE['lang'])) return $_COOKIE['lang'];   // saved choice
    // Accept-Language header — let ICU pick the closest match we support:
    $header = $_SERVER['HTTP_ACCEPT_LANGUAGE'] ?? '';
    if ($header !== '') {
        return Locale::acceptFromHttp($header) ?: 'en';     // "fr-CH,fr;q=0.9" -> "fr_CH"
    }
    return 'en';                                            // safe default
}

<?php
// "5 items" is easy in English, but plural RULES differ wildly:
//   English: 1 = singular, everything else = plural
//   Polish:  different forms for 1, 2–4, and 5+
//   Arabic:  SIX forms (zero, one, two, few, many, other)
// Never build plurals with if/else — use ICU's MessageFormatter {plural}.

$pattern = [
    'en' => '{count, plural, =0 {No items} one {# item} other {# items}}',
    'pl' => '{count, plural, =0 {Brak} one {# produkt} few {# produkty} many {# produktów} other {# produktu}}',
];

foreach (['en', 'pl'] as $locale) {
    echo "[{$locale}]\n";
    foreach ([0, 1, 3, 5] as $count) {
        // ICU reads the locale's plural rules and picks the right form.
        // '#' is replaced by the number, formatted for the locale.
        $text = MessageFormatter::formatMessage($locale, $pattern[$locale], ['count' => $count]);
        echo "  count={$count}: {$text}\n";
    }
}

[en]
  count=0: No items
  count=1: 1 item
  count=3: 3 items
  count=5: 5 items
[pl]
  count=0: Brak
  count=1: 1 produkt
  count=3: 3 produkty
  count=5: 5 produktów

<?php
// 🎯 YOUR TURN — finish this translator so French works too.
// Fill in each blank marked ___ , then run it and check the Output panel.

$messages = [
    'en' => ['hello' => 'Hello, :name!'],
    'fr' => ['hello' => ___],     // 👉 the French greeting, e.g. 'Bonjour, :name !'
];

function t(array $messages, string $locale, string $key, array $params = []): string {
    $msg = $messages[$locale][$key] ?? $messages['en'][$key] ?? $key;
    foreach ($params as $name => $value) {
        // 👉 replace :name etc. with the value. Fill in the search needle:
        $msg = str_replace(___, (string) $value, $msg);   // 👉 e.g. ":{$name}"
    }
    return $msg;
}

echo t($messages, 'en', 'hello', ['name' => 'Sam']) . "\n";
echo t($messages, 'fr', 'hello', ['name' => 'Sam']) . "\n";

// ✅ Expected output:
//    Hello, Sam!
//    Bonjour, Sam !

Hello, Sam!
Bonjour, Sam !

<?php
// 🎯 YOUR TURN — show the same price in two currencies using intl.
// Fill in the ___ blanks, then run it. (Needs the intl extension.)

$price = 49.5;

// 1) A US-dollar formatter for the en-US locale:
$usd = new NumberFormatter('en-US', NumberFormatter::___);  // 👉 CURRENCY
echo $usd->formatCurrency($price, 'USD') . "\n";

// 2) A euro formatter for the de-DE locale:
$eur = new NumberFormatter(___, NumberFormatter::CURRENCY);  // 👉 'de-DE'
echo $eur->formatCurrency($price, 'EUR') . "\n";

// ✅ Expected output (symbols/spacing may vary by ICU version):
//    $49.50
//    49,50 €