Skip to content

5. Internationalisierung

Eine internationalisierte Anwendung zeigt ihre Texte in der Sprache des Benutzers an. Die Fallstudie ist auf Französisch und Englisch verfügbar. Das Prinzip ist einfach: Die Views enthalten keinen Text mehr, sondern Schlüssel ([MENU.HOME]), und ein Wörterbuch pro Sprache ordnet jedem Schlüssel einen Text zu. Die gewählte Sprache wird in einem Cookie gespeichert.

[Symfony] enthält eine Übersetzungskomponente, den Translator, dem wir bereits in Beispiel 09 bei den Validierungsmeldungen begegnet sind. Seine Wörterbücher liegen im Ordner [translations], mit einer Datei pro Domäne und Sprache: [validators.en.yaml] (die Domäne der Validierungsmeldungen, Beispiel 09), [messages.en.yaml] (die Standarddomäne, die für unsere Texte). Das YAML-Format erlaubt verschachtelte Schlüssel: So sind die Wörterbücher der Versionen [ASP.NET Core MVC], [NestJS], [Spring MVC], [Flask] und [Laravel] der Fallstudie aufgebaut, abgesehen von der Syntax. Für die Syntax der Meldungen selbst wählen wir das ICU-Format (International Components for Unicode), einen Standard, den die Erweiterung [intl] von [PHP] interpretieren kann und der beispielsweise Text in die Pluralform flektieren kann. Die Formatierung von Daten und Beträgen bleibt dieselbe wie in Beispiel 16.

5.1. Beispiel 22: Eine zweisprachige Anwendung

22-i18n/
├── config/
│   └── packages/
│       └── framework.yaml
├── src/
│   ├── Controller/
│   │   ├── LanguageController.php
│   │   └── PagesController.php
│   ├── EventListener/
│   │   └── SetLanguage.php
│   ├── Model/
│   │   └── Product.php
│   └── Twig/
│       └── FormatsExtension.php
├── templates/
│   ├── fragments/
│   │   └── navbar.html.twig
│   ├── layout.html.twig
│   └── pages/
│       ├── home.html.twig
│       └── products.html.twig
├── translations/
│   ├── messages+intl-icu.en.yaml
│   └── messages+intl-icu.fr.yaml
└── ...

5.1.1. Die Konfiguration: config/packages/framework.yaml

# config/packages/framework.yaml: die Konfiguration des FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # die Standardsprache und die von der Anwendung unterstützten Sprachen
    default_locale: en
    enabled_locales: ['en', 'fr']
    # der ÜBERSETZUNGS-Service; seine Wörterbücher liegen im Ordner translations/.
    # Ein Schlüssel, der im französischen Wörterbuch fehlt, wird im englischen Wörterbuch gesucht
    translator:
        default_path: '%kernel.project_dir%/translations'
        fallbacks: ['en']
  • Zeile 5: die Standardsprache der Anwendung, die für Anfragen verwendet wird, die keine Sprache angeben (Beispiel 09);
  • Zeile 6: die von der Anwendung unterstützten Sprachen. Diese Liste wird von [Symfony] verwendet (Profiler, Generierung lokalisierter Routen usw.); unser eigener Code hat außerdem seine eigene Liste, im Listener [SetLanguage];
  • Zeilen 9–11: der Übersetzungsservice. [fallbacks] legt die Fallback-Sprache(n) fest: Fehlt ein Schlüssel im Wörterbuch der angeforderten Sprache, wird er im englischen Wörterbuch gesucht. Ein Schlüssel, der in allen Wörterbüchern fehlt, wird unverändert angezeigt: So ist jedes Versäumnis sofort auf dem Bildschirm sichtbar.

5.1.2. Die Wörterbücher

Die Datei [translations/messages+intl-icu.fr.yaml]:

# translations/messages+intl-icu.fr.yaml: das französische Wörterbuch.
# messages: die Standard-Domain; +intl-icu: Die Meldungen folgen der ICU-Syntax
# ({name}: ein Parameter; {n, plural, ...}: eine Meldung, die von einer Zahl abhängt)
MENU:
    HOME: Accueil
    PRODUCTS: Produits
HOME:
    TITLE: Bienvenue
    HELLO: 'Bonjour {name} !'
    DATE: 'Nous sommes le {date}.'
PRODUCTS:
    TITLE: Nos produits
    NAME: Produit
    PRICE: Prix
    COUNT: '{n, plural, =0 {Aucun produit} one {# produit} other {# produits}} au catalogue.'

Der Dateiname besteht aus drei Teilen: der Domäne ([messages], die Standarddomäne), dem Suffix [+intl-icu], das Meldungen im ICU-Format kennzeichnet, und der Sprache ([fr]). Die Schlüssel werden mithilfe der YAML-Verschachtelung nach Themen gruppiert: Der Menüeintrag „Accueil“ hat den Schlüssel [MENU.HOME], wobei die Ebenen durch einen Punkt getrennt sind. Ein Text kann Parameter enthalten, geschrieben als [{name}], die bei der Übersetzung ersetzt werden.

  • Zeile 9: Apostrophe begrenzen einen YAML-String; sie sind notwendig, wenn der Text Zeichen enthält, die YAML interpretiert (geschweifte Klammern, Doppelpunkte usw.);
  • Zeile 15: eine Plural-Meldung. [{n, plural, ...}] wählt anhand des Werts des Parameters [n] eine Form aus: [=0] für genau 0, [one] für den Singular, [other] für den Plural; [#] wird durch die Zahl ersetzt. Die Pluralregeln hängen von der Sprache ab, und ICU kennt sie: Im Französischen sind 0 und 1 Singular, im Englischen dagegen ist 0 Plural („0 products“). Das ist eine Verbesserung gegenüber dem „product(s)“ aus früheren Versionen der Fallstudie.

Die Datei [translations/messages+intl-icu.en.yaml] hat genau dieselben Schlüssel:

# translations/messages+intl-icu.en.yaml: das englische Wörterbuch; dieselben Schlüssel
MENU:
    HOME: Home
    PRODUCTS: Products
HOME:
    TITLE: Welcome
    HELLO: 'Hello {name}!'
    DATE: 'Today is {date}.'
PRODUCTS:
    TITLE: Our products
    NAME: Product
    PRICE: Price
    COUNT: '{n, plural, =0 {No products} one {# product} other {# products}} in the catalogue.'

Ohne das Suffix [+intl-icu] würden die Parameter als [%name%] geschrieben, und der Plural verwendete eine für [Symfony] spezifische Syntax ([{0} Aucun produit|{1} Un produit|]1, Inf[ %n% produits]). Das ICU-Format ist dasjenige, das derzeit von der [Symfony]-Dokumentation empfohlen wird.

5.1.3. Die Sprache jeder Anfrage: src/EventListener/SetLanguage.php

<?php
// src/EventListener/SetLanguage.php: die Sprache jeder Anfrage

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

// Priorität 20: nach dem Routing, vor den Listenern von Symfony, die die Sprache verwenden (siehe Beispiel 16)
#[AsEventListener(event: KernelEvents::REQUEST, priority: 20)]
class SetLanguage
{
    // die unterstützten Sprachen; die erste ist die Standardsprache
    public const LANGUAGES = ['en', 'fr'];

    public const COOKIE = 'language';

    // die Sprache des Cookies [language], falls sie unterstützt wird, sonst Englisch
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $language = $request->cookies->get(self::COOKIE);
        $request->setLocale(in_array($language, self::LANGUAGES, true) ? $language : self::LANGUAGES[0]);
    }
}

Dies ist der [SetLanguage]-Listener aus Beispiel 16, der die Sprache diesmal aus einem Cookie bezieht:

  • Zeile 11: der [kernel.request]-Ereignis-Listener mit Priorität 20: nach dem Routing, aber vor den [Symfony]-Listenern, die die Sprache der Anfrage verwenden (Beispiel 16);
  • Zeilen 15–17: die unterstützten Sprachen und der Cookie-Name: öffentliche Klassenkonstanten, die aus anderen Klassen zugänglich sind ([SetLanguage::LANGUAGES]);
  • Zeilen 22–24: die Sprache der Anfrage: die Sprache des [language]-Cookies, sofern vorhanden und unterstützt; andernfalls Englisch. [$request->cookies] ist die Menge der vom Browser gesendeten Cookies (Beispiel 05); [get] liefert den Wert eines Cookies oder [null]. [in_array] vergleicht mit [true] als drittem Parameter auch die Typen ([===]). [setLocale] legt die Sprache der Anfrage fest: Das ist die Sprache, die der Translator, unsere Formatierungsfilter und der Filter [format_currency] von [Twig] verwenden.

Anders als [Laravel] verschlüsselt [Symfony] Cookies nicht: Das Cookie [language] wird im Klartext übertragen. Das ist unproblematisch: Es enthält keine vertraulichen Informationen, und der Server akzeptiert nur unterstützte Sprachen. Das folgende Beispiel greift die Frage wieder auf, wie viel Vertrauen man einem Cookie schenken kann.

5.1.4. Sprachauswahl: src/Controller/LanguageController.php

<?php
// src/Controller/LanguageController.php: die Wahl der Sprache

namespace App\Controller;

use App\EventListener\SetLanguage;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

class LanguageController extends AbstractController
{
    // GET /language/fr: speichert die Wahl in einem Cookie und kehrt dann zur vorherigen Seite zurück.
    // requirements: Eine andere Sprache als en oder fr passt nicht zur Route (404)
    #[Route('/language/{code}', name: 'language', requirements: ['code' => 'en|fr'], methods: ['GET'])]
    public function change(Request $request, string $code): RedirectResponse
    {
        $response = $this->redirect(self::originPage($request));
        // das Cookie: ein Jahr Lebensdauer, vom JavaScript der Seite nicht lesbar (httpOnly),
        // nie mit einer POST-Anfrage von einer anderen Website gesendet (sameSite lax)
        $response->headers->setCookie(Cookie::create(SetLanguage::COOKIE, $code)
            ->withExpires(new \DateTimeImmutable('+1 year'))
            ->withHttpOnly(true)
            ->withSameSite(Cookie::SAMESITE_LAX));
        return $response;
    }

    // die Seite, von der wir kommen (Header Referer), von der wir nur den Pfad behalten:
    // Eine Weiterleitung auf eine vollständige, aus der Anfrage stammende Adresse würde es erlauben,
    // den Benutzer auf eine andere Website zu schicken (Schwachstelle „Open Redirect“)
    private static function originPage(Request $request): string
    {
        // parse_url zerlegt eine URL in ihre Bestandteile (Pfad, Parameter...)
        $url = parse_url($request->headers->get('Referer', ''));
        $path = $url['path'] ?? '';
        // "//site.com/..." würde vom Browser als Adresse
        // auf einer ANDEREN Website verstanden: ebenfalls abgelehnt
        if (! str_starts_with($path, '/') || str_starts_with($path, '//')) {
            return '/';
        }
        return isset($url['query']) ? "$path?{$url['query']}" : $path;
    }
}
  • Zeile 17: die Route [/language/{code}]. Die Option [requirements] (Beispiel 02) beschränkt den Parameter auf die beiden unterstützten Sprachen: [/language/de] entspricht keiner Route und liefert einen 404-Fehler;
  • Zeile 20: Die Aktion antwortet mit einer Weiterleitung auf die Seite, von der der Benutzer kam: Der Benutzer wird in der neuen Sprache auf seine Seite zurückgeführt;
  • Zeilen 23–26: Die Antwort enthält ein Cookie, das der Browser bei jeder Anfrage zurücksendet. Die Klasse [Cookie] von [Symfony] beschreibt es: [Cookie::create(name, value)] erstellt es, und jede Methode von [with...] liefert eine veränderte Kopie (ein unveränderliches Objekt; siehe Beispiel 03): [withExpires], das Ablaufdatum (in einem Jahr); [withHttpOnly(true)] macht es für das [JavaScript] auf der Seite unsichtbar; [withSameSite(Cookie::SAMESITE_LAX)] verhindert, dass der Browser es mit einer POST-Anfrage von einer anderen Website sendet. ([httpOnly] und [lax] sind übrigens die Standardwerte von [Cookie::create].) [$response->headers->setCookie] fügt es der Antwort als [Set-Cookie]-Header hinzu;
  • Zeilen 33–44: Die ursprüngliche Seite wird durch den Header [Referer] in der Anfrage angegeben (die falsch geschriebene Variante mit nur einem [r] ist die im HTTP-Standard verwendete), den der Browser mit der URL der Seite befüllt, die den Link enthielt. Dieser Header stammt jedoch vom Client, der beliebige Inhalte hineinschreiben kann. Blind auf diese Adresse weiterzuleiten, würde unsere Anwendung zu einem Open Redirect machen: Ein bösartiger Link mit unserem Domainnamen könnte den Benutzer auf eine schädliche Website schicken. Deshalb behalten wir nur den Pfad und die Parameter der URL (die Funktion [parse_url] von [PHP] zerlegt sie in einem assoziativen Array in ihre Bestandteile) und weisen jeden Pfad zurück, der mit [//] beginnt, was der Browser als Adresse einer anderen Website interpretieren würde.

5.1.5. Aktionen: src/Controller/PagesController.php

<?php
// src/Controller/PagesController.php: Die Actions wissen nichts über die Sprache:
// Sie liefern Daten, die Views übersetzen und formatieren sie

namespace App\Controller;

use App\Model\Product;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(methods: ['GET'])]
class PagesController extends AbstractController
{
    #[Route('/', name: 'home')]
    public function home(): Response
    {
        return $this->render('pages/home.html.twig', ['name' => 'Marie',
            'today' => new DateTimeImmutable('2026-09-23')]);
    }

    #[Route('/products', name: 'products')]
    public function products(): Response
    {
        return $this->render('pages/products.html.twig', ['products' => [
            new Product('Keyboard', 2500),
            new Product('Mouse', 1250),
            new Product('Screen', 114900),
        ]]);
    }
}

Die Aktionen sind sprachunabhängig: Sie liefern Rohdaten (einen Namen, ein Datum, Beträge in Cent). Übersetzung und Formatierung übernehmen die Views. Die Klasse [Product] hat einen Namen und einen Preis in Cent; die Erweiterung [FormatsExtension] ist die aus Beispiel 16: Ihr Filter [long_date] schreibt ein Datum im „vollständigen“ Format der Anfragesprache („Wednesday, September 23, 2026“, „mercredi 23 septembre 2026“), und ihr Filter [money] schreibt einen Betrag.

5.1.6. Übersetzen in den Views

<!doctype html>
{# app.request.locale: die Sprache der Anfrage, "en" oder "fr" #}
<html lang="{{ app.request.locale }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# der Titel: der Block [title] der Seite, bereits übersetzt #}
  <title>{% block title %}{% endblock %}</title>
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    {% include 'fragments/navbar.html.twig' %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
</body>
</html>
  • Zeile 3: Das Attribut [lang] der Seite teilt Browsern, Suchmaschinen und Screenreadern ihre Sprache mit; [app.request.locale] ist die Sprache der Anfrage;
  • Zeile 8: Der Seitentitel wird von der Seite selbst geliefert, bereits übersetzt (Block [title]).
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# 'KEY'|trans: die Übersetzung eines Schlüssels in der Sprache der Anfrage #}
    <a class="nav-link" href="{{ path('home') }}">{{ 'MENU.HOME'|trans }}</a>
    <a class="nav-link" href="{{ path('products') }}">{{ 'MENU.PRODUCTS'|trans }}</a>
  </div>
  {# die aktuelle Sprache wird hervorgehoben #}
  <div class="btn-group btn-group-sm">
    {% for code in ['fr', 'en'] %}
      <a class="btn {{ app.request.locale == code ? 'btn-primary' : 'btn-outline-primary' }}"
         href="{{ path('language', {code: code}) }}">{{ code|upper }}</a>
    {% endfor %}
  </div>
</nav>
  • Zeilen 4–5: Der Filter [trans] übersetzt einen Schlüssel in die Sprache der Anfrage;
  • Zeilen 9–12: ein Button pro Sprache, der die Aktion [/language/{code}] auslöst. Die aktuelle Sprache ist hervorgehoben ([btn-primary], ausgefüllter Button).
{% extends 'layout.html.twig' %}
{% block title %}{{ 'HOME.TITLE'|trans }}{% endblock %}

{% block content %}
  <h1>{{ 'HOME.TITLE'|trans }}</h1>
  {# ein Parameter: der Parameter des Filters trans, ein assoziatives Array #}
  <p>{{ 'HOME.HELLO'|trans({name: name}) }}</p>
  {# das Datum, zuerst formatiert (Filter long_date, siehe Beispiel 16), dann als Parameter [date] übergeben #}
  <p>{{ 'HOME.DATE'|trans({date: today|long_date}) }}</p>
{% endblock %}
  • Zeile 2: der übersetzte [title]-Block für das Template;
  • Zeile 7: Die Parameter für einen Text werden in einem assoziativen Array übergeben, einem Parameter des Filters [trans]; [{name}] wird durch den Wert des Schlüssels [name] ersetzt;
  • Zeile 9: das Datum, formatiert in der Anfragesprache vom Filter [long_date] und dann als Parameter übergeben.
{% extends 'layout.html.twig' %}
{% block title %}{{ 'PRODUCTS.TITLE'|trans }}{% endblock %}

{% block content %}
  <h1>{{ 'PRODUCTS.TITLE'|trans }}</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>{{ 'PRODUCTS.NAME'|trans }}</th><th class="text-end">{{ 'PRODUCTS.PRICE'|trans }}</th></tr></thead>
    <tbody>
      {% for product in products %}
        <tr>
          <td>{{ product.name }}</td>
          {# der Filter money aus Beispiel 16: das Format hängt von der Sprache ab #}
          <td class="text-end">{{ product.priceCents|money }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# die Plural-Nachricht: ICU wählt die Form anhand des Parameters n #}
  <p>{{ 'PRODUCTS.COUNT'|trans({n: products|length}) }}</p>
{% endblock %}
  • Zeile 13: der Filter [money], dessen Ergebnis von der Sprache abhängt;
  • Zeile 19: der Parameter [n] für die Pluralform der Meldung: die Anzahl der Produkte ([length], Beispiel 14). Die Produktnamen selbst werden nicht übersetzt: Es sind Daten , die in einer realen Anwendung aus einer Datenbank stammen würden.

Außerhalb von Views ist der Translator ein Service vom Typ [TranslatorInterface], den eine Aktion oder ein Service per Dependency Injection erhalten kann: [$translator->trans('HOME.HELLO', ['name' => 'Marie'])].

5.1.7. Ausführung

Die Startseite auf Englisch (der Standardsprache), dann auf Französisch nach einem Klick auf den Button „FR“:

Image

Image

Die Produktseite in beiden Sprachen. Die Beträge folgen den Konventionen der jeweiligen Sprache:

Image

Image

Der Sprachwechsel, betrachtet mit [curl]. Die Option [-H] liefert den Header [Referer] , den der Browser senden würde:

curl -i -H "Referer: http://localhost:8000/products" http://localhost:8000/language/en
1
2
3
4
5
HTTP/1.1 302 Found
...
Location: /products
...
Set-Cookie: language=en; expires=Mon, 27 Sep 2027 09:47:37 GMT; Max-Age=31536000; path=/; httponly; samesite=lax

Die Weiterleitung führt zur ursprünglichen Seite zurück ([Symfony] schreibt eine relative URL, die der Browser vervollständigt), und das Cookie wird für ein Jahr gesetzt. Ein [Referer] , der auf eine andere Website verweist, führt nicht dorthin: Es wird nur sein Pfad beibehalten.

curl -i -H "Referer: https://pirate.example/trap" http://localhost:8000/language/en
curl -i -H "Referer: http://localhost:8000//pirate.example/x" http://localhost:8000/language/fr
1
2
3
4
5
6
HTTP/1.1 302 Found
Location: /trap
...
HTTP/1.1 302 Found
Location: /
...

Die Seite [/trap] existiert auf unserer Website nicht: Der Benutzer erhält einen 404-Fehler, bleibt aber auf unserer Website. Schließlich die Startseite, angefordert mit dem Cookie [language=en] (Option [-b] von [curl]):

curl -b "language=en" http://localhost:8000/
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Welcome</title>
...
        <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/products">Products</a>
...
    <p>Hello Marie!</p>
    <p>Today is Wednesday, September 23, 2026.</p>
...

Eine andere Möglichkeit zur Wahl der Sprache wäre gewesen, den Header [Accept-Language] des Browsers auszulesen (Beispiel 12; [$request->getPreferredLanguage(['fr', 'en'])] wählt die beste Sprache aus den unterstützten aus). Beide werden oft kombiniert: die Browsersprache beim ersten Besuch, danach die vom Benutzer gewählte Sprache. Eine dritte Methode, die häufig mit [Symfony] verwendet wird, legt die Sprache in die URL ([/en/products]): Ein spezieller Routenparameter, [{_locale}], legt dann selbst die Sprache der Anfrage fest. Diese Fallstudie konzentriert sich auf das Cookie mit Englisch als Standardsprache.