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 für jede Sprache ordnet jedem Schlüssel einen Text zu. Die gewählte Sprache wird in einem Cookie gespeichert.

[ASP.NET Core] verfügt über ein eigenes Übersetzungssystem (die Schnittstelle [IStringLocalizer] und die Ressourcendateien [.resx]). Wir verwenden stattdessen JSON-Wörterbücher, die von einer eigens dafür geschriebenen kleinen Klasse gelesen werden: Es sind dieselben Dateien wie in der [NestJS]-Version der Fallstudie, und ihr Format lässt sich ohne spezielle Werkzeuge lesen und schreiben. Die Auswahl der Sprache für jede Anfrage überlassen wir jedoch [ASP.NET Core]: Das ist die Aufgabe seiner Lokalisierungs-Middleware.

5.1. Beispiel 22: Eine zweisprachige Anwendung

22-i18n/
├── Controllers/
│   ├── LanguageController.cs
│   └── PagesController.cs
├── i18n/
│   ├── en.json
│   └── fr.json
├── Translation/
│   ├── Translator.cs
│   └── ViewPage.cs
├── Views/
│   ├── Pages/
│   │   ├── Home.cshtml
│   │   └── Products.cshtml
│   ├── Shared/
│   │   ├── _Layout.cshtml
│   │   └── _Navbar.cshtml
│   ├── _ViewImports.cshtml
│   └── _ViewStart.cshtml
├── wwwroot/
│   └── css/
│       └── styles.css
├── appsettings.json
├── Example22.csproj
└── Program.cs

5.1.1. Wörterbücher

Die Datei [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 [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, organisiert nach Seite oder Thema: Der Schlüssel [HOME.HELLO] bezeichnet 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 erzeugt.

5.1.2. Der Übersetzungs-Service

Die Datei [Translation/Translator.cs]:

using System.Globalization;
using System.Text.Json;
using System.Text.RegularExpressions;

namespace Example22.Translation;

// die Wörterbücher, EINMAL beim Start gelesen: der Service ist ein Singleton
public partial class Translator
{
    public static readonly string[] Languages = ["fr", "en"];
    public const string DefaultLanguage = "en";

    // Sprache -> (vollständiger Schlüssel "HOME.HELLO" -> Text)
    private readonly Dictionary<string, Dictionary<string, string>> dictionaries = [];

    public Translator(IWebHostEnvironment environment)
    {
        foreach (var language in Languages)
        {
            var path = Path.Combine(environment.ContentRootPath, "i18n", $"{language}.json");
            using var document = JsonDocument.Parse(File.ReadAllText(path));
            var dictionary = new Dictionary<string, string>();
            Flatten(document.RootElement, "", dictionary);
            dictionaries[language] = dictionary;
        }
    }

    // die Sprache der aktuellen Anfrage, von der Lokalisierungs-Middleware gesetzt
    public static string CurrentLanguage()
    {
        var language = CultureInfo.CurrentUICulture.TwoLetterISOLanguageName;
        return Languages.Contains(language) ? language : DefaultLanguage;
    }

    // Translate("HOME.HELLO", { ["name"] = "Marie" }) -> "Hello Marie!"
    public string Translate(string? key, IReadOnlyDictionary<string, string>? parameters = null)
    {
        if (string.IsNullOrEmpty(key)) return "";
        // ein fehlender Schlüssel zeigt den Schlüssel selbst an: ein Versäumnis fällt auf dem Bildschirm auf
        var text = dictionaries[CurrentLanguage()].GetValueOrDefault(key) ?? key;
        if (parameters is null) return text;
        // jedes {name} wird durch den Wert des gleichnamigen Parameters ersetzt
        return Parameter().Replace(text, m => parameters.TryGetValue(m.Groups[1].Value, out var value) ? value : m.Value);
    }

    // { "MENU": { "HOME": "Home" } } -> { "MENU.HOME": "Home" }
    private static void Flatten(JsonElement node, string prefix, Dictionary<string, string> result)
    {
        foreach (var property in node.EnumerateObject())
        {
            var key = prefix == "" ? property.Name : $"{prefix}.{property.Name}";
            if (property.Value.ValueKind == JsonValueKind.Object)
            {
                Flatten(property.Value, key, result);
            }
            else
            {
                result[key] = property.Value.GetString() ?? "";
            }
        }
    }

    // der reguläre Ausdruck {name}, vom C#-Compiler kompiliert
    [GeneratedRegex(@"\{(\w+)\}")]
    private static partial Regex Parameter();
}

Kommentieren wir diesen Code:

  • Zeile 8: Das Schlüsselwort [partial] wird vom regulären Ausdruck am Ende der Datei benötigt (siehe unten);
  • Zeilen 10–11: die unterstützten Sprachen und die Standardsprache;
  • Zeile 14: für jede Sprache ein [C#] -Dictionary, das jedem vollständigen Schlüssel ([HOME.HELLO]) seinen Text zuordnet;
  • Zeilen 16–24: Der Konstruktor liest die JSON-Dateien. Der [IWebHostEnvironment]-Service, bereitgestellt von [ASP.NET Core], liefert den Projektordner ([ContentRootPath]). [JsonDocument.Parse] analysiert den JSON-Text; [using var] gibt das Objekt am Ende des Blocks frei. Der Service wird ein Singleton sein (siehe [Program.cs]): Die Dateien werden nur einmal gelesen;
  • Zeilen 29–32: die Sprache der aktuellen Anfrage. Wir werden sehen, dass die Lokalisierungs-Middleware sie in [CultureInfo.CurrentUICulture] ablegt. [TwoLetterISOLanguageName] liefert den zweistelligen Code ([fr], [en]);
  • Zeilen 36–43: die Übersetzung. Der Schlüssel wird im Wörterbuch der aktuellen Sprache gesucht; wird er nicht gefunden, wird der Schlüssel selbst angezeigt: Eine Auslassung ist auf dem Bildschirm sofort sichtbar. Der reguläre Ausdruck findet jeden Parameter [{name}] im Text und ersetzt ihn durch seinen Wert; ein Parameter ohne Wert bleibt unverändert;
  • Zeilen 47–58: Die Funktion „flacht“ das JSON „ab“: Das Objekt ["HOME": { "HELLO": "..." }] ergibt den Schlüssel [HOME.HELLO]. Sie ruft sich selbst auf (rekursive Funktion), um verschachtelte Objekte zu durchlaufen;
  • Zeilen 64–65: der reguläre Ausdruck [\{(\w+)\}] (eine öffnende geschweifte Klammer, ein oder mehrere Wortzeichen, erfasst, eine schließende geschweifte Klammer). Das Attribut [[GeneratedRegex]] weist den Compiler an, den Code für die Auswertung einmalig bei der Kompilierung zu erzeugen. Die Methode wird als [partial] deklariert: Ihr Rumpf wird vom Compiler erzeugt.

5.1.3. Umsetzung in den Views

Eine View könnte den Service mit der Direktive [@inject Translator Translator] beziehen und dann [@Translator.Translate("MENU.HOME")] schreiben. Das ist mühsam und müsste in jeder View wiederholt werden. Wir wählen einen anderen Ansatz: Jede [Razor]-View wird in eine [C#]-Klasse kompiliert, die standardmäßig von der Klasse [RazorPage<TModel>] des Frameworks abgeleitet ist. Wir können unsere eigene Klasse dazwischenschalten, die allen Views die benötigten Methoden bereitstellt. Die Datei [Translation/ViewPage.cs]:

using System.Globalization;
using Microsoft.AspNetCore.Mvc.Razor;
using Microsoft.AspNetCore.Mvc.Razor.Internal;

namespace Example22.Translation;

// die Basisklasse aller Views (siehe Views/_ViewImports.cshtml: @inherits)
public abstract class ViewPage<TModel> : RazorPage<TModel>
{
    // per Dependency Injection gefüllt, wie es @inject in einer View täte
    [RazorInject]
    public Translator Translator { get; set; } = null!;

    // @T("HOME.HELLO", ("name", "Marie")): die Parameter sind Paare (name, value)
    public string T(string? key, params (string Name, object? Value)[] parameters) =>
        Translator.Translate(key, parameters.ToDictionary(p => p.Name, p => p.Value?.ToString() ?? ""));

    // "fr" oder "en"
    public string Language => Translator.CurrentLanguage();

    // ein ausgeschriebenes Datum in der aktuellen Sprache
    public string LongDate(DateOnly date) => date.ToString("D", CultureInfo.CurrentCulture);

    // ein Betrag in Euro, im Format der aktuellen Sprache
    public string Money(decimal amount)
    {
        var format = (NumberFormatInfo)CultureInfo.CurrentCulture.NumberFormat.Clone();
        format.CurrencySymbol = "€";
        return amount.ToString("C", format);
    }
}

Kommentieren wir diesen Code:

  • Zeile 8: Eine generische Klasse – [TModel] ist der Typ des View-Modells, der für jede View verschieden ist. Die Klasse ist abstrakt: Nur die Views erben von ihr;
  • Zeilen 11–12: Das Attribut [[RazorInject]] weist [Razor] an, die Eigenschaft per Dependency Injection zu befüllen: Das ist das Äquivalent zu [@inject] für eine Klasse;
  • Zeilen 15–16: Die Methode [T] übersetzt einen Schlüssel. Ihre Parameter sind [(name, value)]-Tupel: eine kompakte Syntax zum Schreiben von Wertepaaren, [("name", "Marie")]. Das Schlüsselwort [params] erlaubt es, beliebig viele davon, durch Kommas getrennt, zu übergeben. Die Methode organisiert sie in einem Dictionary für den Service. Der gelieferte Text ist ein String: [Razor] maskiert ihn wie jeden [@]-Ausdruck;
  • Zeile 19: die aktuelle Sprache, [fr] oder [en];
  • Zeilen 22–29: Datumsangaben und Beträge werden gemäß der aktuellen Kultur formatiert, die ebenfalls von der Lokalisierungs-Middleware gesetzt wird (siehe Beispiel 16).

Die Datei [Views/_ViewImports.cshtml]:

1
2
3
4
5
6
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using Example22.Controllers
@using Example22.Translation
@* alle Views leiten von ViewPage ab: sie haben T(...), Language...;
   TModel bezeichnet den Modelltyp jeder View (@model ...) *@
@inherits ViewPage<TModel>
  • Zeile 6: Die Direktive [@inherits] legt die Elternklasse der Views fest. In [_ViewImports.cshtml] platziert, gilt sie für alle. Jede View kann nun [@T("MENU.HOME")] schreiben.

5.1.4. Sprachauswahl

Die Datei [Program.cs]:

using System.Globalization;
using System.Text.Encodings.Web;
using System.Text.Unicode;
using Example22.Translation;
using Microsoft.AspNetCore.Localization;
using Microsoft.Extensions.FileProviders;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
// die Wörterbücher: eine einzige Instanz, bei erstem Bedarf erstellt
builder.Services.AddSingleton<Translator>();

var app = builder.Build();

app.UseStaticFiles();
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
    RequestPath = "/bootstrap",
});

// die Sprache jeder Anfrage: die des Cookies, sonst Englisch
var cultures = Translator.Languages.Select(l => new CultureInfo(l)).ToList();
var localization = new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture(Translator.DefaultLanguage),
    SupportedCultures = cultures,   // die Sprachen der Formate (Datumsangaben, Zahlen)
    SupportedUICultures = cultures, // die Sprachen der Texte
};
// nur das Cookie entscheidet (weder die Browsersprache noch ein URL-Parameter)
localization.RequestCultureProviders = [new CookieRequestCultureProvider()];
app.UseRequestLocalization(localization);

app.MapControllers();
app.Run();

Gehen wir diesen Code durch:

  • Zeile 12: der Übersetzungs-Service mit einer einzigen Instanz;
  • Zeilen 24–29: die Konfiguration der Lokalisierungs-Middleware. [.NET] unterscheidet zwei Konzepte: die Kultur ([CurrentCulture]), die das Format von Datumsangaben und Zahlen festlegt, und die Oberflächenkultur ([CurrentUICulture]), die die Sprache der Texte festlegt. Beiden wird hier dieselbe Sprachliste zugewiesen; eine Sprache, die nicht in der Liste steht, wird abgelehnt;
  • Zeile 32: wo die Sprache der Anfrage gesucht wird. Standardmäßig prüft die Middleware der Reihe nach einen Parameter der URL ([?culture=en]), ein Cookie und dann den vom Browser gesendeten Header [Accept-Language] (seine Sprache). Nur das Cookie wird beibehalten: Der Benutzer trifft die Auswahl über die Schaltflächen FR / EN;
  • Zeile 33: Die Middleware wird der Pipeline hinzugefügt. Für jede Anfrage liest sie das Cookie und setzt [CultureInfo.CurrentCulture] und [CultureInfo.CurrentUICulture] für die Dauer der Anfrage. Ist kein Cookie vorhanden, ist die Standardsprache Englisch.

Die Datei [Controllers/LanguageController.cs]:

using Example22.Translation;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

namespace Example22.Controllers;

public class LanguageController : Controller
{
    // GET /language/fr: speichert die Auswahl in einem Cookie und kehrt dann zur vorherigen Seite zurück
    [HttpGet("language/{language}")]
    public IActionResult Change(string language)
    {
        if (!Translator.Languages.Contains(language))
        {
            return NotFound();
        }
        Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,                              // der Name des Cookies
            CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(language)), // "c=fr|uic=fr"
            new CookieOptions { MaxAge = TimeSpan.FromDays(365), SameSite = SameSiteMode.Lax, HttpOnly = true });
        return Redirect(OriginPage());
    }

    // die Seite, von der wir kommen (Header Referer), 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 string OriginPage()
    {
        var referer = Request.Headers.Referer.ToString();
        if (!Uri.TryCreate(referer, UriKind.Absolute, out var url))
        {
            return "/";
        }
        return url.PathAndQuery;
    }
}

Gehen wir diesen Code durch:

  • Zeilen 10–21: [GET /language/en] speichert die Auswahl in einem Cookie mit einem Jahr Gültigkeit und leitet dann auf die Seite um, von der der Benutzer kam. Eine unbekannte Sprache führt zu einem 404-Fehler;
  • Zeilen 17–20: [Response.Cookies.Append(name, value, options)] setzt ein Cookie: Der Browser sendet es bei jeder folgenden Anfrage zurück. Name und Format seines Wertes sind die, welche die Lokalisierungs-Middleware erwartet: Wir erhalten sie von der Klasse [CookieRequestCultureProvider], ohne sie selbst schreiben zu müssen. Optionen: [MaxAge] (Lebensdauer), [HttpOnly] (das [JavaScript] der Seite kann es nicht lesen), [SameSite = Lax] (es wird nicht bei POST-Anfragen gesendet, die von anderen Websites kommen);
  • Zeilen 27–34: 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 ([PathAndQuery]): Eine Umleitung auf eine vollständige URL aus der Anfrage würde es einer bösartigen Website erlauben, einen Link zu erstellen, der den Benutzer nach dem Durchlaufen unserer Website auf die bösartige Website schickt (eine Schwachstelle, bekannt als [open redirect]).

5.1.5. Die Views

Die Datei [Views/Shared/_Layout.cshtml]:

<!doctype html>
<html lang="@Language">
<head>
  <meta charset="utf-8">
  @* der Titel ist ein SCHLÜSSEL, von der View gesetzt, vom Layout übersetzt *@
  <title>@T(ViewData["Title"] as string)</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <partial name="_Navbar" />
    @RenderBody()
  </div>
</body>
</html>
  • Zeile 2: Das Attribut [lang] der Seite gibt die gewählte Sprache wieder (nützlich für Screenreader und Rechtschreibprüfungen);
  • Zeile 6: Der Seitentitel ist ein Schlüssel, den die View in [ViewData] ablegt und das Template übersetzt. [as string] wandelt den Wert (vom Typ [object]) in einen String um, oder in [null] , wenn er keiner ist.

Die Datei [Views/Shared/_Navbar.cshtml]:

<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    <a class="nav-link" href="/">@T("MENU.HOME")</a>
    <a class="nav-link" href="/products">@T("MENU.PRODUCTS")</a>
  </div>
  @* die aktuelle Sprache wird hervorgehoben *@
  <div class="btn-group btn-group-sm">
    <a class="btn @(Language == "fr" ? "btn-primary" : "btn-outline-primary")" href="/language/fr">FR</a>
    <a class="btn @(Language == "en" ? "btn-primary" : "btn-outline-primary")" href="/language/en">EN</a>
  </div>
</nav>
  • Zeilen 8–9: zwei Links (der Wechsel der Sprache ändert keine Anwendungsdaten: Ein GET genügt), wobei die aktuelle Sprache hervorgehoben ist.

Die Datei [Views/Pages/Home.cshtml]:

1
2
3
4
5
6
7
@model HomeModel
@{
    ViewData["Title"] = "HOME.TITLE";
}
<h1>@T("HOME.TITLE")</h1>
<p>@T("HOME.HELLO", ("name", Model.Name))</p>
<p>@T("HOME.DATE", ("date", LongDate(Model.Today)))</p>
  • Zeile 6: ein Parameter, als Tupel übergeben;
  • Zeile 7: Das Datum wird zuerst von [LongDate] formatiert und dann als Parameter [date] an [T] übergeben.

Die Datei [Views/Pages/Products.cshtml]:

@model List<Product>
@{
    ViewData["Title"] = "PRODUCTS.TITLE";
}
<h1>@T("PRODUCTS.TITLE")</h1>
<table class="table table-sm w-auto">
  <thead><tr><th>@T("PRODUCTS.NAME")</th><th class="text-end">@T("PRODUCTS.PRICE")</th></tr></thead>
  <tbody>
    @foreach (var product in Model)
    {
      <tr><td>@product.Name</td><td class="text-end">@Money(product.Price)</td></tr>
    }
  </tbody>
</table>
<p>@T("PRODUCTS.COUNT", ("n", Model.Count))</p>
  • Zeile 11: der Betrag, gemäß der Sprache formatiert;
  • Zeile 15: ein numerischer Parameter; [T] wandelt ihn in einen String um.

Die Datei [Controllers/PagesController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example22.Controllers;

public record Product(string Name, decimal Price);

public record HomeModel(string Name, DateOnly Today);

public class PagesController : Controller
{
    [HttpGet("/")]
    public IActionResult Home()
    {
        return View(new HomeModel("Marie", new DateOnly(2026, 9, 23)));
    }

    [HttpGet("products")]
    public IActionResult Products()
    {
        List<Product> products =
        [
            new Product("Keyboard", 25m),
            new Product("Mouse", 12.5m),
            new Product("Screen", 1149m),
        ];
        return View(products);
    }
}

Die Actions sind sprachunabhängig: Sie liefern Daten, und die Views übersetzen und formatieren sie.

5.1.6. Ausführung

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

Image

Image

Ein Klick auf FR, 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/fr
1
2
3
4
HTTP/1.1 302 Found
Content-Length: 0
Location: /products
Set-Cookie: .AspNetCore.Culture=c%3Dfr%7Cuic%3Dfr; max-age=31536000; path=/; samesite=lax; httponly

Der Server setzt das Cookie [.AspNetCore.Culture], dessen kodierter Wert [c=fr|uic=fr] lautet (die Kultur und die Oberflächenkultur), und leitet auf die ursprüngliche Seite um, die nun auf Französisch ist:

Image

Image

Eine nicht unterstützte Sprache:

curl -i http://localhost:5000/language/de
HTTP/1.1 404 Not Found
Content-Length: 0

Die Fallstudie geht genau so vor und verwendet umfangreichere Wörterbücher ([i18n/fr.json] und [i18n/en.json]): derselbe Service ([Translator]), dieselbe Eltern-Klasse der Views (mit einigen zusätzlichen Eigenschaften), derselbe Controller ([/language/{language}]), dasselbe Cookie. Es gibt nur einen Unterschied: Die von der Geschäfts- und der Web-Schicht erzeugten Fehlermeldungen sind ebenfalls Schlüssel, die erst im letzten Moment von der View übersetzt werden.