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.

[Spring] hat ein eigenes Übersetzungssystem: das Interface [MessageSource], dessen Standardimplementierung Dateien wie [messages_fr.properties], [messages_en.properties] ... liest. Wir behalten das Interface bei, da [Spring] und [Thymeleaf] es für die Übersetzung verwenden, implementieren es aber selbst mit einer kleinen Klasse, die JSON-Wörterbücher liest: Es sind dieselben Dateien wie in den Versionen [ASP.NET Core MVC] und [NestJS] der Fallstudie, und ihr Format lässt sich ohne spezielle Werkzeuge lesen und schreiben. Die Auswahl der Sprache für jede Anfrage überlassen wir dagegen [Spring MVC]: Dafür ist sein Sprachresolver ([LocaleResolver]) zuständig, dem wir in Beispiel 16 begegnet sind.

5.1. Beispiel 22: Eine zweisprachige Anwendung

22-i18n/
├── src/main/java/example22/
│   ├── config/
│   │   └── WebConfig.java
│   ├── controllers/
│   │   ├── LanguageController.java
│   │   └── PagesController.java
│   ├── translation/
│   │   ├── Formats.java
│   │   └── Translator.java
│   └── Example22Application.java
├── src/main/resources/
│   ├── i18n/
│   │   ├── en.json
│   │   └── fr.json
│   ├── static/css/
│   │   └── styles.css
│   ├── templates/
│   │   ├── fragments/
│   │   │   └── navbar.html
│   │   ├── pages/
│   │   │   ├── home.html
│   │   │   └── products.html
│   │   └── layout.html
│   └── application.properties
└── pom.xml

Die Dateien [pom.xml] (der Starter [Thymeleaf]), [application.properties] (Port 5000), [Example22Application.java] (die Startklasse) und [styles.css] sind dieselben wie in den vorherigen Beispielen.

5.1.1. Die Wörterbücher

Die Datei [src/main/resources/i18n/fr.json]:

{
  "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} produit(s) au catalogue."
  }
}

Die Datei [src/main/resources/i18n/en.json]:

{
  "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} product(s) in the catalogue."
  }
}
  • Ein Wörterbuch ist eine JSON-Datei, die nach Seiten oder Themen gegliedert ist: Der Schlüssel [HOME.HELLO] verweist auf den Text [HELLO] im Abschnitt [HOME];
  • Zeile 8: Ein Text kann Parameter in geschweiften Klammern enthalten, die bei der Übersetzung ersetzt werden. Die Wortstellung ist von Sprache zu Sprache verschieden: Deshalb wird ein Text nicht einfach durch Aneinanderreihen übersetzter Segmente zusammengesetzt.

Die Wörterbücher liegen in [src/main/resources]: [Maven] kopiert diesen Ordner zusammen mit den kompilierten Klassen nach [target/classes]. Sie sind daher Teil des Klassenpfads – der Menge der Ordner und Archive, in denen [Java] nach den Klassen und Ressourcen der Anwendung sucht: Dort liest das Programm sie, unabhängig vom Ordner, aus dem es gestartet wird.

5.1.2. Der Übersetzungs-Service

Die Datei [translation/Translator.java] in zwei Teilen. Der erste Teil liest die Wörterbücher und übersetzt:

package example22.translation;

import java.io.IOException;
import java.io.InputStream;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import org.springframework.context.MessageSource;
import org.springframework.context.MessageSourceResolvable;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;

import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;

// der Übersetzungsservice: die JSON-Wörterbücher, EINMAL beim Start gelesen.
// Er implementiert das Spring-Interface MessageSource und heißt [messageSource]:
// Spring verwendet ihn dann für ALLE Übersetzungen und Thymeleaf für die
// Ausdrücke #{...} der Views.
@Component("messageSource")
public class Translator implements MessageSource {

    public static final List<String> LANGUAGES = List.of("fr", "en");
    public static final String DEFAULT_LANGUAGE = "en";

    // {name}: ein Parameter in einem Text
    private static final Pattern PARAMETER = Pattern.compile("\\{(\\w+)\\}");

    // Sprache -> (vollständiger Schlüssel "HOME.HELLO" -> Text)
    private final Map<String, Map<String, String>> dictionaries = new HashMap<>();

    public Translator() throws IOException {
        ObjectMapper json = new ObjectMapper();
        for (String language : LANGUAGES) {
            // die Wörterbücher liegen in src/main/resources/i18n, also im Classpath
            try (InputStream stream = new ClassPathResource("i18n/" + language + ".json").getInputStream()) {
                Map<String, String> dictionary = new HashMap<>();
                flatten(json.readTree(stream), "", dictionary);
                dictionaries.put(language, dictionary);
            }
        }
    }

    // die nächstliegende unterstützte Sprache zu [locale]: "fr_FR" -> "fr"; "de" -> "en"
    public static String language(Locale locale) {
        String language = locale == null ? "" : locale.getLanguage();
        return LANGUAGES.contains(language) ? language : DEFAULT_LANGUAGE;
    }

    // translate("HOME.HELLO", ["name", "Marie"], en) -> "Hello Marie!"
    // Die Parameter werden als Paare (Name, Wert) übergeben.
    public String translate(String key, Object[] parameters, Locale locale) {
        if (key == null || key.isEmpty()) {
            return "";
        }
        // ein fehlender Schlüssel zeigt den Schlüssel selbst an: ein Versäumnis ist auf dem Bildschirm sichtbar
        String text = dictionaries.get(language(locale)).getOrDefault(key, key);
        if (parameters == null || parameters.length == 0) {
            return text;
        }
        Map<String, String> values = new HashMap<>();
        for (int i = 0; i + 1 < parameters.length; i += 2) {
            values.put(String.valueOf(parameters[i]), String.valueOf(parameters[i + 1]));
        }
        // jedes {name} wird durch den Wert des gleichnamigen Parameters ersetzt
        Matcher m = PARAMETER.matcher(text);
        return m.replaceAll(r -> Matcher.quoteReplacement(values.getOrDefault(r.group(1), r.group())));
    }

    // { "MENU": { "HOME": "Home" } } -> { "MENU.HOME": "Home" }
    private static void flatten(JsonNode node, String prefix, Map<String, String> result) {
        for (Map.Entry<String, JsonNode> property : node.properties()) {
            String key = prefix.isEmpty() ? property.getKey() : prefix + "." + property.getKey();
            if (property.getValue().isObject()) {
                flatten(property.getValue(), key, result);
            } else {
                result.put(key, property.getValue().asString());
            }
        }
    }

Gehen wir diesen Code durch:

  • Zeilen 24–25: Der Service ist eine Bean (annotiert mit [@Component]) und damit ein Singleton: Die Dateien werden nur einmal beim Start gelesen. Er implementiert das Interface [MessageSource] von [Spring] und heißt [messageSource], wie von der Annotation festgelegt. Dieser Name ist nicht zufällig gewählt: Unter diesem Namen sucht [Spring] den Übersetzungs-Service der Anwendung. [Spring Boot], das standardmäßig einen erzeugt (er würde die Dateien [messages*.properties] lesen), verzichtet darauf, sobald eine Bean mit diesem Namen existiert;
  • Zeilen 27–28: die unterstützten Sprachen und die Standardsprache. [List.of] erzeugt eine schreibgeschützte Liste;
  • Zeile 31: der reguläre Ausdruck [\{(\w+)\}] (eine öffnende geschweifte Klammer, ein oder mehrere Wortzeichen, erfasst, eine schließende geschweifte Klammer), der Parameter in einem Text erkennt. In einem [Java]-String wird der Backslash als [\\] geschrieben. [Pattern.compile] parst ihn ein für alle Mal;
  • Zeile 34: für jede Sprache ein [Java]-Wörterbuch ([Map]), das jedem vollständigen Schlüssel ([HOME.HELLO]) seinen Text zuordnet;
  • Zeilen 36–46: Der Konstruktor liest die JSON-Dateien. [ClassPathResource] verweist auf eine Datei im Klassenpfad (siehe oben). Die Anweisung [try (...)] (bekannt als „try-with-resources“-Anweisung) schließt den in ihren Klammern geöffneten Stream am Ende des Blocks automatisch, auch wenn ein Fehler auftritt. Das Objekt [ObjectMapper] der Bibliothek [Jackson] (derjenigen, die [Spring] für JSON verwendet) parst den Text und wandelt ihn in einen [JsonNode]-Knotenbaum um;
  • Zeilen 49–52: die unterstützte Sprache, die einer beliebigen Sprache am nächsten kommt. Ein [Locale]-Objekt vom Typ [Java] bezeichnet eine Sprache, gegebenenfalls mit Angabe eines Landes ([fr], [en_US] ...); [getLanguage()] liefert ihren aus zwei Buchstaben bestehenden Code. Eine nicht unterstützte Sprache ([de]) ergibt die Standardsprache;
  • Zeilen 56–72: die Übersetzung. Der Schlüssel wird im Wörterbuch der angeforderten Sprache nachgeschlagen; wird er nicht gefunden, wird der Schlüssel selbst angezeigt ([getOrDefault]): Eine Lücke ist sofort auf dem Bildschirm sichtbar;
  • Zeilen 65–68: Die Parameter werden in einem Array [Object[]] als Paare (Name, Wert) gespeichert: [["name", "Marie"]]. Die Schleife ordnet sie zu einem Wörterbuch [name -> value]. Wir werden sehen, warum dieses etwas ungewöhnliche Format gewählt wurde;
  • Zeilen 70–71: [replaceAll] ersetzt jeden im Text gefundenen Parameter [{name}] durch das Ergebnis des Lambdas: den Wert des gleichnamigen Parameters ([r.group(1)] ist der in Klammern erfasste Teil) oder den Parameter selbst, unverändert, wenn er keinen Wert hat ([r.group()] ist der gesamte gefundene Text). [Matcher.quoteReplacement] schützt die Zeichen [$] und [\] , die ein Wert enthalten könnte und die für [replaceAll] sonst eine besondere Bedeutung haben;
  • Zeilen 75–84: Die Methode „flacht“ JSON ab: Das Objekt ["HOME": { "HELLO": "..." }] ergibt den Schlüssel [HOME.HELLO]. Sie ruft sich selbst auf (rekursive Methode), um verschachtelte Objekte zu durchlaufen. [properties()] liefert die Paare (Name, Wert) eines JSON-Objekts; [asString()] liefert den Wert eines Textes.

Der zweite Teil implementiert das Interface [MessageSource]:

    // ------------------------------------------------ das Interface MessageSource

    @Override
    public String getMessage(String code, Object[] args, String defaultMessage, Locale locale) {
        return translate(code, args, locale);
    }

    @Override
    public String getMessage(String code, Object[] args, Locale locale) {
        return translate(code, args, locale);
    }

    // eine durch mehrere mögliche Codes beschriebene Meldung (die Validierungsfehler):
    // der erste im Wörterbuch vorhandene Code gewinnt
    @Override
    public String getMessage(MessageSourceResolvable message, Locale locale) {
        Map<String, String> dictionary = dictionaries.get(language(locale));
        String[] codes = message.getCodes() == null ? new String[0] : message.getCodes();
        for (String code : codes) {
            if (dictionary.containsKey(code)) {
                return translate(code, message.getArguments(), locale);
            }
        }
        String defaultText = message.getDefaultMessage();
        return defaultText != null ? defaultText : (codes.length > 0 ? codes[0] : "");
    }
}
  • Zeilen 3–11: die beiden Methoden, die einen Code (einen Schlüssel) und seine Argumente in eine bestimmte Sprache übersetzen; sie rufen [translate] auf. Die Annotation [@Override] weist den Compiler an zu prüfen, dass tatsächlich eine Methode des Interface überschrieben wird;
  • Zeilen 15–26: Die dritte Methode erhält ein Objekt [MessageSourceResolvable], das eine Nachricht anhand mehrerer möglicher Codes beschreibt, vom spezifischsten bis zum allgemeinsten. So beschreibt [Spring] Validierungsfehler (siehe Beispiel 19): Eine Einschränkung [@NotBlank] für das Feld [name] eines Objekts [person] ergibt die Codes [NotBlank.person.name], [NotBlank.name], [NotBlank] ... Der erste im Wörterbuch vorhandene Code hat Vorrang; ist keiner vorhanden, wird die Standardnachricht oder der erste Code zurückgegeben. Die Fallstudie nutzt dies, um ihre Fehlermeldungen zu übersetzen.

In [Spring] ist das übliche Format für Nachrichtenparameter positionsbasiert: [Hello {0}!], wobei das erste Argument [{0}] ersetzt. Wir bevorzugen benannte Parameter, die in einem Wörterbuch lesbarer sind ([Hello {name}!]) und mit denen in den anderen Versionen der Fallstudie identisch sind. Das Interface [MessageSource] übergibt jedoch nur ein Array von Argumenten – daher die Konvention von (Name, Wert)-Paaren.

5.1.3. Übersetzen in Views

In einer [Thymeleaf]-View ist der Ausdruck [#{KEY}] – in Beispiel 14 bereits kurz mit dem Array eingeführt – die Übersetzung des Schlüssels [KEY] in die Sprache der Anfrage: [Thymeleaf] ruft die Bean [messageSource] auf, also unseren [Translator]. Argumente werden in Klammern übergeben: [#{HOME.HELLO('name', ${name})}] ruft [getMessage("HOME.HELLO", ["name", "Marie"], language)] auf. Auf der View-Seite müssen keine Klassen geschrieben werden – das ist der Vorteil, das [Spring]-Interface implementiert zu haben.

Bleiben die Datumsangaben und Beträge, die nicht übersetzt, sondern je nach Sprache formatiert werden. Die Datei [translation/Formats.java]:

package example22.translation;

import java.math.BigDecimal;
import java.text.NumberFormat;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.Currency;

import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.stereotype.Component;

// Daten und Beträge, in der Sprache der Anfrage formatiert (siehe Beispiel 16)
@Component("formats")
public class Formats {

    // ein Datum in ausgeschriebener Form
    public String longDate(LocalDate date) {
        return date.format(DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(LocaleContextHolder.getLocale()));
    }

    // ein Betrag in Euro
    public String money(BigDecimal amount) {
        NumberFormat format = NumberFormat.getCurrencyInstance(LocaleContextHolder.getLocale());
        format.setCurrency(Currency.getInstance("EUR"));
        return format.format(amount);
    }
}

Das ist mehr oder weniger die Klasse aus Beispiel 16:

  • Zeile 14: eine Bean mit dem Namen [formats], auf die die Views als [${@formats.longDate(...)}] verweisen;
  • Zeilen 19 und 24: [LocaleContextHolder.getLocale()] gibt die Sprache der aktuellen Anfrage an. Wir werden sehen, wer sie setzt;
  • Zeile 19: ein Datum im langen Format ([FormatStyle.FULL]) in dieser Sprache;
  • Zeilen 24–26: ein Betrag im Währungsformat dieser Sprache, unabhängig von der Sprache in Euro.

5.1.4. Auswahl der Sprache

Die Datei [config/WebConfig.java]:

package example22.config;

import java.time.Duration;
import java.util.Locale;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

// die Konfiguration von Spring MVC, ergänzt
@Configuration
public class WebConfig implements WebMvcConfigurer {

    // Bootstrap, von den Beispielen gemeinsam genutzt: der Ordner examples/common/bootstrap
    // wird unter der URL /bootstrap/... bereitgestellt
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/bootstrap/**")
                // "file:": ein Ordner auf der Festplatte, relativ zum aktuellen Ordner. Zwei
                // Versuche: Start aus dem Ordner des Beispiels oder aus [examples]
                .addResourceLocations("file:../common/bootstrap/", "file:common/bootstrap/");
    }

    // die Sprache jeder Anfrage: die des Cookies [language], sonst Englisch.
    // Die Bean muss [localeResolver] heißen: unter diesem Namen sucht Spring sie.
    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver("language");
        resolver.setDefaultLocale(Locale.ENGLISH);
        resolver.setCookieMaxAge(Duration.ofDays(365));
        resolver.setCookieHttpOnly(true);
        resolver.setCookieSameSite("Lax");
        return resolver;
    }
}

Gehen wir diesen Code durch:

  • Zeilen 19–25: die Dateien von [Bootstrap] wie in den vorherigen Beispielen;
  • Zeilen 29–37: Die Bean [localeResolver] (das ist der Name, unter dem [Spring MVC] sie sucht) legt die Sprache für jede Anfrage fest. Zu Beginn jeder Anfrage fragt [Spring MVC] sie nach der Sprache und speichert sie für die Dauer der Anfrage in [LocaleContextHolder]: Die Methoden von [Formats], die Ausdrücke [#{...}] von [Thymeleaf] und die Variable [#locale] in den Views rufen sie von dort ab;
  • Zeile 31: Ein [CookieLocaleResolver], bereitgestellt von [Spring], liest die Sprache aus einem Cookie, hier mit dem Namen [language]. Das Cookie enthält den Sprachcode ([en]);
  • Zeile 32: Ohne Cookie ist die Sprache Englisch. Beachten Sie, dass die Sprache des Browsers (Header [Accept-Language]) dann ignoriert wird: Der Benutzer wählt die Sprache über die Schaltflächen FR / EN;
  • Zeilen 33–35: die Eigenschaften des Cookies, das [CookieLocaleResolver] beim Ändern der Sprache schreibt: eine Lebensdauer von einem Jahr; [HttpOnly] (das [JavaScript] der Seite kann es nicht lesen); [SameSite=Lax] (es wird nicht bei POST-Anfragen von anderen Sites gesendet).

Die Datei [controllers/LanguageController.java]:

package example22.controllers;

import java.net.URI;
import java.util.Locale;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.LocaleResolver;

import example22.translation.Translator;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Controller
public class LanguageController {

    private final LocaleResolver localeResolver;

    public LanguageController(LocaleResolver localeResolver) {
        this.localeResolver = localeResolver;
    }

    // GET /language/fr: speichert die Auswahl in einem Cookie und kehrt dann zur vorherigen Seite zurück
    @GetMapping("/language/{language}")
    public String change(@PathVariable String language, HttpServletRequest request, HttpServletResponse response) {
        if (!Translator.LANGUAGES.contains(language)) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND);
        }
        // der LocaleResolver schreibt sein Cookie selbst (Name, Wert, Lebensdauer ...)
        localeResolver.setLocale(request, response, Locale.forLanguageTag(language));
        return "redirect:" + originPage(request);
    }

    // die Seite, von der wir kommen (Referer-Header), von der wir nur den Pfad behalten:
    // eine Weiterleitung auf eine vollständige, der Anfrage entnommene Adresse würde es
    // erlauben, den Benutzer auf eine andere Website zu schicken (Schwachstelle "Open Redirect")
    private static String originPage(HttpServletRequest request) {
        String referer = request.getHeader("Referer");
        try {
            URI url = URI.create(referer);
            String path = url.getRawPath();
            // "//site.com/..." würde vom Browser als Adresse
            // auf einer ANDEREN Website verstanden: ebenfalls abgelehnt
            if (path == null || !path.startsWith("/") || path.startsWith("//")) {
                return "/";
            }
            return url.getRawQuery() == null ? path : path + "?" + url.getRawQuery();
        } catch (RuntimeException e) {
            // kein Referer-Header (NullPointerException) oder eine ungültige Adresse
            return "/";
        }
    }
}

Gehen wir diesen Code durch:

  • Zeilen 20–24: Der Controller erhält [LocaleResolver] per Dependency Injection;
  • Zeilen 27–35: [GET /language/fr] speichert die Auswahl in einem Cookie und leitet dann auf die Seite um, von der der Benutzer kam. Eine unbekannte Sprache löst einen 404-Fehler aus ([ResponseStatusException], siehe Beispiel 21);
  • Zeile 33: Wir erzeugen das Cookie nicht selbst, sondern bitten [LocaleResolver] darum, die Sprache zu ändern; er schreibt das Cookie mit dem Namen und den Eigenschaften, die in [WebConfig] festgelegt sind. [Locale.forLanguageTag("en")] erzeugt das Objekt [Locale] für Englisch;
  • Zeile 34: [redirect:] fordert eine Umleitung an (siehe Beispiel 04);
  • Zeilen 40–55: Die ursprüngliche Seite wird durch den Header [Referer] angegeben, den der Browser beim Klick auf einen Link hinzufügt. Wir behalten nur den Pfad und die Parameter ([getRawPath], [getRawQuery]: so, wie sie in der Adresse stehen, ohne Decodierung). Eine Umleitung auf eine vollständige URL aus der Anfrage würde es einer bösartigen Site erlauben, einen Link zu erstellen, der den Benutzer nach dem Durchgang durch unsere Site auf die bösartige Site weiterleitet (eine Schwachstelle, bekannt als [open redirect]);
  • Zeilen 45–49: Ein Pfad, der mit zwei Schrägstrichen beginnt, wird ebenfalls abgelehnt: Der Browser würde [//pirate.example/trap] als die Adresse [http://pirate.example/trap] auf einer anderen Site interpretieren;
  • Zeilen 51–54: Ohne den Header [Referer] löst [URI.create(null)] eine [NullPointerException] aus; eine ungültige Adresse eine [IllegalArgumentException]. Beide sind von [RuntimeException] abgeleitet: Man gelangt dann zurück auf die Startseite.

5.1.5. Die Views

Die Datei [templates/layout.html]:

<!doctype html>
<!--/* #locale: die Sprache der Anfrage; ihr aus zwei Buchstaben bestehender Code: #locale.language */-->
<html xmlns:th="http://www.thymeleaf.org" th:lang="${#locale.language}" th:fragment="page(title, content)">
<head>
  <meta charset="utf-8">
  <!--/* der Titel ist ein SCHLÜSSEL, von der Seite geliefert, vom Layout übersetzt */-->
  <title th:text="#{${title}}">Title</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <nav th:replace="~{fragments/navbar :: navbar}"></nav>
    <main th:replace="${content}"></main>
  </div>
</body>
</html>
  • Zeile 3: Das Template (siehe Beispiel 15) ist ein Fragment mit zwei Parametern: dem Seitentitel und dem Seiteninhalt. Das Attribut [lang] der Seite spiegelt die gewählte Sprache wider (nützlich für Screenreader und Rechtschreibprüfungen): [#locale] ist die Sprache der Anfrage, und [#locale.language] ist ihr aus zwei Buchstaben bestehender Code;
  • Zeile 7: Der Seitentitel ist ein Schlüssel, der von der Seite bereitgestellt und vom Template übersetzt wird: In [#{${title}}] ist der Schlüssel selbst das Ergebnis eines Ausdrucks;
  • Zeile 13: die Navigationsleiste, ein Fragment aus einer anderen Datei.

Die Datei [templates/fragments/navbar.html]:

<nav class="navbar navbar-expand bg-light rounded mb-3 px-3" th:fragment="navbar">
  <div class="navbar-nav me-auto">
    <!--/* #{KEY}: die Übersetzung eines Schlüssels, in der Sprache der Anfrage */-->
    <a class="nav-link" href="/" th:text="#{MENU.HOME}">Home</a>
    <a class="nav-link" href="/products" th:text="#{MENU.PRODUCTS}">Products</a>
  </div>
  <!--/* die aktuelle Sprache wird hervorgehoben */-->
  <div class="btn-group btn-group-sm" th:with="language=${#locale.language}">
    <a class="btn" th:classappend="${language == 'fr'} ? 'btn-primary' : 'btn-outline-primary'" href="/language/fr">FR</a>
    <a class="btn" th:classappend="${language == 'en'} ? 'btn-primary' : 'btn-outline-primary'" href="/language/en">EN</a>
  </div>
</nav>
  • Zeilen 4–5: zwei übersetzte Texte. Der im Tag geschriebene Text ([Home]) wird nur angezeigt, wenn die Datei direkt im Browser geöffnet wird; [Thymeleaf] ersetzt ihn durch die Übersetzung;
  • Zeile 8: [th:with] definiert eine lokale Variable, [language], die innerhalb des Tags und seiner untergeordneten Tags verwendet werden kann;
  • Zeilen 9–10: zwei Links (ein Sprachwechsel ändert keine Anwendungsdaten: ein GET genügt), wobei die aktuelle Sprache hervorgehoben ist: [th:classappend] fügt den Klassen des Tags eine CSS-Klasse hinzu.

Die Datei [templates/pages/home.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('HOME.TITLE', ~{::main})}">
<body>
<main>
  <h1 th:text="#{HOME.TITLE}">Welcome</h1>
  <!--/* ein Parameter: das Paar (Name des Parameters, Wert) */-->
  <p th:text="#{HOME.HELLO('name', ${name})}">Hello Marie!</p>
  <!--/* das Datum, zuerst formatiert, dann als Parameter [date] übergeben */-->
  <p th:text="#{HOME.DATE('date', ${@formats.longDate(today)})}">Today is...</p>
</main>
</body>
</html>
  • Zeile 2: Die Seite ruft das Template auf und verwendet dabei den Schlüssel für ihren Titel und Inhalt (das Tag [main]);
  • Zeile 7: ein Parameter, übergeben als Paar (Name, Wert);
  • Zeile 9: Das Datum wird zunächst vom Bean [formats] formatiert und dann als Parameter [date] an die Nachricht übergeben.

Die Datei [templates/pages/products.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('PRODUCTS.TITLE', ~{::main})}">
<body>
<main>
  <h1 th:text="#{PRODUCTS.TITLE}">Our products</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th th:text="#{PRODUCTS.NAME}">Product</th><th class="text-end" th:text="#{PRODUCTS.PRICE}">Price</th></tr></thead>
    <tbody>
      <tr th:each="product : ${products}">
        <td th:text="${product.name}">Keyboard</td>
        <td class="text-end" th:text="${@formats.money(product.price)}">€25.00</td>
      </tr>
    </tbody>
  </table>
  <p th:text="#{PRODUCTS.COUNT('n', ${#lists.size(products)})}">3 product(s) in the catalogue.</p>
</main>
</body>
</html>
  • Zeile 11: der Betrag, formatiert entsprechend der Sprache;
  • Zeile 15: ein numerischer Parameter: [#lists.size] gibt die Größe der Liste an; [Translator] wandelt den Wert in eine Zeichenkette um ([String.valueOf]).

Die Datei [controllers/PagesController.java]:

package example22.controllers;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

// die Actions wissen nichts über die Sprache: sie liefern Daten,
// die Views übersetzen und formatieren sie
@Controller
public class PagesController {

    public record Product(String name, BigDecimal price) {
    }

    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("name", "Marie");
        model.addAttribute("today", LocalDate.of(2026, 9, 23));
        return "pages/home";
    }

    @GetMapping("/products")
    public String products(Model model) {
        model.addAttribute("products", List.of(
                new Product("Keyboard", new BigDecimal("25")),
                new Product("Mouse", new BigDecimal("12.5")),
                new Product("Screen", new BigDecimal("1149"))));
        return "pages/products";
    }
}

Actions sind sprachunabhängig: Sie liefern Daten, während die Views sie übersetzen und formatieren. Der Preis ist ein [BigDecimal]; der [Java]-Typ für exakte Dezimalzahlen eignet sich für Geldbeträge (Zeile 16). Das Datum auf der Startseite ist ein festes Datum, der 23. September 2026 (Zeile 22), und nicht das aktuelle Datum: Die nachstehenden Ergebnisse hängen daher nicht vom Tag der Ausführung des Beispiels ab.

5.1.6. Ausführung

Auf Englisch (noch kein Cookie), unter der URL http://localhost:5000/ und http://localhost:5000/products:

Image

Image

Ein Klick auf eine Sprachschaltfläche (hier EN), simuliert mit [curl] (die Option [-H] fügt den Header [Referer] hinzu, den der Browser gesendet hätte):

curl -i -H "Referer: http://localhost:5000/products" http://localhost:5000/language/en
1
2
3
4
HTTP/1.1 302
Set-Cookie: language=en; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:23 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/products
Content-Length: 0

[CookieLocaleResolver] setzt das Cookie [language] mit dem Wert [en] und den angeforderten Eigenschaften ([Max-Age] und [Expires] geben beide die Lebensdauer an, und zwar für ältere bzw. neuere Browser). Die Weiterleitung führt zur ursprünglichen Seite zurück ([Tomcat]; der Server hat den Pfad [/products] zu einer vollständigen Adresse erweitert). Ein Klick auf FR funktioniert genauso (Cookie [language=fr]): Die Seiten sind nun auf Französisch:

Image

Image

Die Datumsangaben und Beträge haben sich angepasst: „mercredi 23 septembre 2026“, „1 149,00 €“.

Eine bösartige Website, die versucht, unsere Weiterleitung auszunutzen, würde nur eine Seite unserer eigenen Website sehen:

curl -i -H "Referer: https://pirate.example/trap?x=1" http://localhost:5000/language/fr
curl -i -H "Referer: https://pirate.example//pirate.example/trap" http://localhost:5000/language/fr
1
2
3
4
5
6
7
8
9
HTTP/1.1 302
Set-Cookie: language=fr; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:24 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/trap?x=1
Content-Length: 0

HTTP/1.1 302
Set-Cookie: language=fr; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:24 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/
Content-Length: 0

Eine nicht unterstützte Sprache:

curl -i http://localhost:5000/language/de
1
2
3
4
HTTP/1.1 404
Content-Type: application/json

{"timestamp":"2026-09-25T16:49:23.993Z","status":404,"error":"Not Found","message":"404 NOT_FOUND","path":"/language/de"}

Die Standard-Fehlerantwort von [Spring Boot]: JSON für [curl], eine HTML-Seite für einen Browser. Kapitel 7 zeigt, wie sie durch eine eigene Seite ersetzt wird.

Denken Sie schließlich daran, dass ein Cookie vom Client kontrolliert wird. Ein manuell erstelltes Cookie [language=de] wird von [CookieLocaleResolver] akzeptiert: Der Text bleibt englisch (die Standardsprache von [Translator]), aber das Datum wird auf Deutsch formatiert:

curl -b "language=de" http://localhost:5000/
1
2
3
<html lang="de">
  <p>Hello Marie!</p>
  <p>Today is Mittwoch, 23. September 2026.</p>

(Es sind nur drei Zeilen der Seite dargestellt.) Das ist nicht weiter schlimm: Der Benutzer täuscht nur sich selbst.

Die Fallstudie funktioniert genau so, mit umfangreicheren Wörterbüchern ([i18n/fr.json] und [i18n/en.json]): dasselbe Bean [messageSource], derselbe [CookieLocaleResolver], derselbe Controller [/language/{language}]. Der einzige Unterschied besteht darin, dass auch die von der Geschäfts- und der Web-Schicht erzeugten Fehlermeldungen Schlüssel sind, die erst im letzten Moment von der View übersetzt werden.