Globalisierung und Lokalisierung in ASP.NET Core Blazor

2025-06-27

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Informationen zum aktuellen Release finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der Supportrichtlinie für .NET und .NET Core. Informationen zum aktuellen Release finden Sie in der .NET 9-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Informationen zum aktuellen Release finden Sie in der .NET 9-Version dieses Artikels.

In diesem Artikel wird erläutert, wie Sie globalisierte und lokalisierte Inhalte für Benutzer*innen in verschiedenen Kulturen und Sprachen rendern.

Globalisierung und Lokalisierung

Für die Globalisierung ermöglicht Blazor eine Formatierung von Zahlen und Datumsangaben. Für die Lokalisierung rendert Blazor Inhalte unter Verwendung des .NET-Ressourcensystems.

Lokalisierungsfeatures von ASP.NET Core werden eingeschränkt unterstützt:

Unterstützt:IStringLocalizer und IStringLocalizer<T> werden in Blazor-Apps unterstützt.

Nicht unterstützt:IHtmlLocalizer und IViewLocalizer sind ASP.NET Core MVC Funktionen und nicht unterstützt in Blazor Apps.

Für Blazor Apps werden lokalisierte Nachrichten für die Formularvalidierung mit Datenanmerkungen unterstützt, wenn DisplayAttribute.ResourceType und ValidationAttribute.ErrorMessageResourceType implementiert sind.

In diesem Artikel wird beschrieben, wie die Globalisierungs- und Lokalisierungsfeatures von Blazor basierend auf folgenden Angaben verwendet werden:

Der Accept-Language-Header, der vom Browser basierend auf den Bevorzugten Sprachen des Benutzers in den Browsereinstellungen festgelegt wird.
Eine von der App festgelegte Kultur, die nicht auf dem Wert der Accept-Language-Überschrift basiert. Die Einstellung kann für alle Benutzer statisch oder abhängig von der App-Logik dynamisch sein. Wenn die Einstellung auf der Voreinstellung des Benutzers basiert, wird die Einstellung in der Regel gespeichert und bei zukünftigen Besuchen erneut geladen.

Allgemeine Informationen finden Sie unter den folgenden Ressourcen:

Häufig werden die Begriffe Sprache und Kultur synonym verwendet, wenn es um Globalisierungs- und Lokalisierungskonzepte geht.

In diesem Artikel bezieht sich die Sprache auf die Auswahl, die von einem Benutzer in den Einstellungen des Browsers getroffen wurde. Die Spracheinstellungen des Benutzers werden in Browseranfragen im Accept-Language-Header übermittelt. Browsereinstellungen verwenden in der Regel das Wort „Sprache“ in der Benutzeroberfläche.

Kultur bezieht sich auf Mitglieder von .NET und Blazor-API. Zum Beispiel kann die Anfrage eines Benutzers die Accept-Language Kopfzeile enthalten, die aus der Perspektive des Benutzers eine Sprache angibt, aber die App legt letztendlich die CurrentCulture ("Kultur")-Eigenschaft basierend auf der vom Benutzer angeforderten Sprache fest. Die API verwendet in der Regel das Wort „culture“ im Namen ihrer Member.

Die Anleitung in diesem Artikel umfasst nicht das Festlegen des HTML-Sprachattributs der Seite (<html lang="...">), das von Barrierefreiheitswerkzeugen verwendet wird. Sie können den Wert statisch festlegen, indem Sie eine Sprache dem lang-Attribut des <html>-Tags oder document.documentElement.lang in JavaScript zuweisen. Sie können den Wert von document.documentElement.lang dynamisch mit JS-Interop festlegen.

Hinweis

Die Codebeispiele in diesem Artikel verwenden Nullwerte zulassende Verweistypen (Nullable Reference Types, NRTs) und die statische Analyse des NULL-Zustands des .NET-Compilers, die in ASP.NET Core in .NET 6 oder höher unterstützt werden. Entfernen Sie bei der Zielbestimmung von .NET 5 oder früher die NULL-Typbezeichnung (?) aus den Beispielen des Artikels.

Globalisierung

Die Attributanweisung @bind wendet Formate an und analysiert Werte für die Anzeige basierend auf der ersten bevorzugten Sprache des*der Benutzer*in, die die App unterstützt. @bind unterstützt den @bind:culture-Parameter, um ein System.Globalization.CultureInfo für das Parsen und Formatieren eines Wertes bereitzustellen.

Der Zugriff auf die aktuelle Kultur kann über die System.Globalization.CultureInfo.CurrentCulture-Eigenschaft erfolgen.

CultureInfo.InvariantCulture wird für die folgenden Feldtypen verwendet (<input type="{TYPE}" />, wobei der {TYPE} Platzhalter der Typ ist):

date
number

Diese Feldtypen:

werden basierend auf ihren entsprechenden browserbasierten Formatierungsregeln angezeigt.
können keinen Freiformtext enthalten.
bieten Benutzerinteraktionsmerkmale basierend auf der Implementierung des Browsers.

Blazor bietet integrierte Unterstützung, um Werte in der aktuellen Kultur darzustellen. Daher wird nicht empfohlen, eine Kultur mit @bind:culture anzugeben, wenn die Feldtypen date und number verwendet werden.

Die folgenden Feldtypen haben spezifische Formatierungsanforderungen und werden nicht von allen großen Browsern unterstützt, daher werden sie nicht von Blazor unterstützt:

datetime-local
month
week

Informationen zur aktuellen Browserunterstützung der vorangehenden Typen finden Sie unter Can I use.

Unterstützung der .NET-Globalisierung und internationaler Komponenten für Unicode (Blazor WebAssembly)

Blazor WebAssembly verwendet eine reduzierte Globalisierungs-API und eine Reihe integrierter Internationaler Komponenten für Unicode (ICU)-Gebiete. Weitere Informationen finden Sie unter .NET-Globalisierung und ICU: ICU auf WebAssembly.

Informationen zum Laden einer benutzerdefinierten ICU-Datendatei zum Steuern der Gebietsschemas der App finden Sie unter WASM Globalization Icu (WASM-Globalisierung ICU). Derzeit ist das manuelle Erstellen der benutzerdefinierten ICU-Datendatei erforderlich. .NET-Tools zur Vereinfachung des Erstellungsprozesses der Datei sind für .NET 10 im November 2025 geplant.

Das Laden einer benutzerdefinierten Teilmenge von Gebietsschemas in einer Blazor WebAssembly-App wird in .NET 8 oder höher unterstützt. Weitere Informationen finden Sie in diesem Abschnitt für eine .NET 8- oder höher-Version dieses Artikels.

Invariante Globalisierung

Dieser Abschnitt gilt nur für clientseitige Blazor-Szenarien.

Wenn für die App keine Lokalisierung erforderlich ist, konfigurieren Sie die App so, dass die invariante Kultur unterstützt wird, die in der Regel auf US-Englisch (en-US) basiert. Die Verwendung von invarianten Globalisierungsfunktionen reduziert die Downloadgröße der App und führt zu einem schnelleren Start der App. Legen Sie die InvariantGlobalization-Eigenschaft in der Projektdatei der App (true) auf .csproj fest:

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

Alternativ können Sie die invariante Globalisierung mit folgenden Ansätzen konfigurieren:

In runtimeconfig.json:

{
  "runtimeOptions": {
    "configProperties": {
      "System.Globalization.Invariant": true
    }
  }
}

Mit einer Umgebungsvariable:
- Schlüssel: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
- Wert: true oder 1

Weitere Informationen finden Sie unter Laufzeitkonfigurationsoptionen für Globalisierung (.NET-Dokumentation).

Zeitzoneninformationen

Dieser Abschnitt gilt nur für clientseitige Blazor-Szenarien.

Die Einführung einer invarianten Globalisierung führt nur dazu, dass nicht lokalisierte Zeitzonennamen verwendet werden. Um den Zeitzonencode und die Daten zu kürzen, was die Downloadgröße der App reduziert und zu einem schnelleren Start der App führt, wenden Sie die <InvariantTimezone> MSBuild-Eigenschaft mit einem Wert von true in der Projektdatei der App an:

<PropertyGroup>
  <InvariantTimezone>true</InvariantTimezone>
</PropertyGroup>

Hinweis

<BlazorEnableTimeZoneSupport>überschreibt eine frühere <InvariantTimezone>-Einstellung. Wir empfehlen, die <BlazorEnableTimeZoneSupport>-Einstellung zu entfernen.

Eine Datendatei wird eingeschlossen, damit die Zeitzoneninformationen korrekt sind. Wenn die App diese Funktion nicht benötigt, sollten Sie in Erwägung ziehen, sie zu deaktivieren, indem Sie die <BlazorEnableTimeZoneSupport> MSBuild-Eigenschaft im Projektfile der App auf false setzen:

<PropertyGroup>
  <BlazorEnableTimeZoneSupport>false</BlazorEnableTimeZoneSupport>
</PropertyGroup>

Demokomponente

Die folgende CultureExample1-Komponente kann verwendet werden, um die Globalisierungs- und Lokalisierungskonzepte von Blazor zu veranschaulichen, die in diesem Artikel behandelt werden.

CultureExample1.razor:

@page "/culture-example-1"
@using System.Globalization

<h1>Culture Example 1</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Rendered values</h2>

<ul>
    <li><b>Date</b>: @dt</li>
    <li><b>Number</b>: @number.ToString("N2")</li>
</ul>

<h2><code>&lt;input&gt;</code> elements that don't set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.CurrentCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input @bind="number" /></label></li>
</ul>

<h2><code>&lt;input&gt;</code> elements that set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.InvariantCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input type="date" @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input type="number" @bind="number" /></label></li>
</ul>

@code {
    private DateTime dt = DateTime.Now;
    private double number = 1999.69;
}

Das Zahlenzeichenfolgenformat (N2) im obigen Beispiel (.ToString("N2")) ist ein standardmäßiger numerischer .NET-Formatbezeichner. Das N2-Format wird für alle numerischen Typen unterstützt, enthält ein Gruppentrennzeichen und rendert bis zu zwei Dezimalstellen.

Fügen Sie der Navigation in der NavMenu-Komponente (NavMenu.razor) für die CultureExample1-Komponente optional ein Menüelement hinzu.

Dynamisches Festlegen der Kultur über den `Accept-Language`-Header

Fügen Sie der App das Paket Microsoft.Extensions.Localization hinzu.

Der Accept-Language-Header wird vom Browser festgelegt und durch die Bevorzugte Sprache des Benutzers in den Browsereinstellungen gesteuert. In den Browsereinstellungen legt ein Benutzer eine oder mehrere bevorzugte Sprachen in der gewünschten Reihenfolge fest. Die Reihenfolge der Einstellung wird vom Browser verwendet, um Qualitätswerte (q, 0-1) für die einzelnen Sprachen im Header festzulegen. Im folgenden Beispiel wird US-Englisch, Englisch und Costa Rica-Spanisch mit Bevorzugung von US-Englisch oder Englisch angegeben:

Bevorzugte Sprache: en-US,en;q=0.9,es-CR;q=0.8

Die Kultur der App wird durch Abgleich der ersten angeforderten Sprache festgelegt, die mit einer unterstützten Kultur der App übereinstimmt.

Legen Sie bei clientseitiger Entwicklung die BlazorWebAssemblyLoadAllGlobalizationData-Eigenschaft in der Projektdatei der clientseitigen App (true) auf .csproj fest:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Bei clientseitiger Entwicklung wird das dynamische Festlegen der Kultur aus dem Header Accept-Language nicht unterstützt.

Hinweis

Wenn die Spezifikation der App eine Beschränkung der unterstützten Kulturen auf eine explizite Liste erfordert, lesen Sie den Abschnitt Dynamisches Festlegen der clientseitigen Kultur durch Benutzereinstellung in diesem Artikel.

Apps werden mit Lokalisierungsmiddleware lokalisiert. Fügen Sie der App mit AddLocalization Lokalisierungsdienste hinzu.

Fügen Sie in der Datei Program die folgende Zeile hinzu, in der Dienste registriert sind:

builder.Services.AddLocalization();

In Server-seitige Entwicklung geben Sie die unterstützten Kulturen der App an, bevor jegliche Middleware, die die Anforderungskultur überprüfen könnte. Setzen Sie im Allgemeinen die Anforderungs-Lokalisierungs-Middleware unmittelbar vor dem Aufruf von MapRazorComponents ein. Im folgenden Beispiel werden unterstützte Kulturen für US-Englisch und Costa Rica-Spanisch konfiguriert:

In Server-seitige Entwicklung geben Sie die von der App unterstützten Kulturen unmittelbar nach dem Hinzufügen der Routing-Middleware (UseRouting) zur Verarbeitungspipeline an. Im folgenden Beispiel werden unterstützte Kulturen für US-Englisch und Costa Rica-Spanisch konfiguriert:

app.UseRequestLocalization(new RequestLocalizationOptions()
    .AddSupportedCultures(new[] { "en-US", "es-CR" })
    .AddSupportedUICultures(new[] { "en-US", "es-CR" }));

Informationen zur Anordnung der Lokalisierungsmiddleware in der Middlewarepipeline der Program-Datei finden Sie unter ASP.NET Core-Middleware.

Verwenden Sie die Im Abschnitt CultureExample1 gezeigte -Komponente, um die Funktionsweise der Globalisierung zu untersuchen. Erstellen Sie eine Anforderung mit US-Englisch (en-US). Wechseln Sie in den Spracheinstellungen des Browsers zu Costa Rica-Spanisch (es-CR). Fordern Sie die Webseite erneut an.

Wenn die Kultur US-Englisch (en-US) ist, verwendet die gerenderte Komponente die Monat/Tag-Datumsformatierung (6/7), 12-Stunden-Zeitangaben (AM/PM) und Kommatrennzeichen in Zahlen mit einem Punkt für den Dezimalwert (1,999.69):

Datum: 7.6.2021 6:45:22
Nummer: 1.999,69

Wenn als Kultur Costa Rica-Spanisch (es-CR) verwendet wird, verwendet die gerenderte Komponente die Tag/Monat-Datumsformatierung (7/6), 24-Stunden-Zeitangaben und Punkttrennzeichen in Zahlen mit einem Komma für den Dezimalwert (1.999,69):

Datum: 6.7.2021 6:49:38
Nummer: 1.999,69

Statisches Festlegen der clientseitigen Kultur

Legen Sie die BlazorWebAssemblyLoadAllGlobalizationData-Eigenschaft in der Projektdatei der App (true) auf .csproj fest:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Die Konfiguration des Intermediate Language (IL) Linkers für die clientseitige Darstellung entfernt Internationalisierungsinformationen, außer für explizit angeforderte Gebietsschemas. Weitere Informationen finden Sie unter Konfigurieren des Linkers für Blazor in ASP.NET Core.

Die Kultur der App kann in JavaScript festgelegt werden, wenn Blazor mit der applicationCulture-Startoption Blazor gestartet wird. Im folgenden Beispiel wird die App so konfiguriert, dass sie mit der Kultur US-Englisch (en-US) gestartet wird.

Verhindern Sie den Blazor-Autostart, indem Sie autostart="false" zum Blazor-Tag von <script> hinzufügen:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>

Im vorangegangenen Beispiel entspricht der {BLAZOR SCRIPT}-Platzhalter dem Pfad und Dateinamen des Blazor-Skripts. Informationen zum Speicherort des Skripts finden Sie unter Projektstruktur für ASP.NET Core Blazor.

Fügen Sie den folgenden <script> Block nach dem Blazor Tag von <script> und vor dem abschließenden </body> Tag ein:

Blazor Web App:

<script>
  Blazor.start({
    webAssembly: {
      applicationCulture: 'en-US'
    }
  });
</script>

Blazor WebAssembly eigenständig:

<script>
  Blazor.start({
    applicationCulture: 'en-US'
  });
</script>

Der Wert von applicationCulture muss dem Sprachentagformat BCP-47 entsprechen. Weitere Informationen zum Start von Blazor finden Sie unter Starten von ASP.NET Core Blazor.

Eine Alternative zum Festlegen der Startoption von Blazor für die Kultur ist das Festlegen der Kultur in C#-Code. Legen Sie CultureInfo.DefaultThreadCurrentCulture und CultureInfo.DefaultThreadCurrentUICulture in der Program-Datei auf dieselbe Kultur fest.

Fügen Sie den Namespace System.Globalization der Program-Datei hinzu:

using System.Globalization;

Fügen Sie die Kultureinstellungen vor der Zeile hinzu, die WebAssemblyHostBuilder erstellt und ausführt (await builder.Build().RunAsync();):

CultureInfo.DefaultThreadCurrentCulture = new CultureInfo("en-US");
CultureInfo.DefaultThreadCurrentUICulture = new CultureInfo("en-US");

Hinweis

Derzeit laden Blazor WebAssembly-Apps nur Ressourcen basierend auf DefaultThreadCurrentCulture. Weitere Informationen finden Sie unter Blazor. WASM verlässt sich ausschließlich auf die aktuelle Kultur (die aktuelle UI-Kultur wird nicht berücksichtigt) (dotnet/aspnetcore #56824).

Statisches Festlegen der serverseitigen Kultur

Serverseitige Apps werden über Lokalisierungsmiddleware lokalisiert. Fügen Sie der App mit AddLocalization Lokalisierungsdienste hinzu.

In der Datei Program:

builder.Services.AddLocalization();

Geben Sie die statische Kultur in der Program-Datei an, bevor eine Middleware, die die Anforderungskultur überprüfen könnte. Im Allgemeinen platzieren Sie die Anforderungs-Lokalisierungs-Middleware unmittelbar vor MapRazorComponents. Im folgenden Beispiel wird US-Englisch konfiguriert:

Geben Sie die statische Kultur in der Program-Datei unmittelbar nach der Hinzufügung der Routing-Middleware (UseRouting) zur Verarbeitungspipeline an. Im folgenden Beispiel wird US-Englisch konfiguriert:

app.UseRequestLocalization("en-US");

Der Kulturwert für UseRequestLocalization muss dem Sprachentagformat BCP-47 entsprechen.

Informationen zur Anordnung der Lokalisierungsmiddleware in der Middlewarepipeline der Program-Datei finden Sie unter ASP.NET Core-Middleware.

Serverseitige Apps werden über Lokalisierungsmiddleware lokalisiert. Fügen Sie der App mit AddLocalization Lokalisierungsdienste hinzu.

In Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Geben Sie unmittelbar nach dem Hinzufügen der Routing-Middleware zur Verarbeitungspipeline die statische Kultur in Startup.Configure (Startup.cs) an. Im folgenden Beispiel wird US-Englisch konfiguriert:

app.UseRequestLocalization("en-US");

Der Kulturwert für UseRequestLocalization muss dem Sprachentagformat BCP-47 entsprechen.

Informationen zur Anordnung der Lokalisierungsmiddleware in der Middlewarepipeline von Startup.Configure finden Sie unter ASP.NET Core-Middleware.

Dynamisches Festlegen der clientseitigen Kultur durch Benutzereinstellung

Beispiele für Speicherorte, an denen eine App die Einstellungen von Benutzer*innen speichern kann, sind der lokale Speicher des Browsers (bei clientseitigen Szenarios üblich), in einem cookie oder einer Datenbank für die Lokalisierung (bei serverseitigen Szenarios üblich) oder in einem externen Dienst, der an eine externe Datenbank angefügt und über eine Web-API zugänglich ist. Im folgenden Beispiel wird die Verwendung des lokalen Speichers im Browser veranschaulicht.

Fügen Sie der App das Paket Microsoft.Extensions.Localization hinzu.

Hinweis

Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

Legen Sie die BlazorWebAssemblyLoadAllGlobalizationData-Eigenschaft in der Projektdatei auf true fest:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Die Kultur der App für clientseitiges Rendering (CSR) wird mithilfe der API des Blazor-Frameworks festgelegt. Die Kulturauswahl eines Benutzers kann im lokalen Browserspeicher gespeichert werden.

Stellen Sie JS-Funktionen nach dem Blazor-Tag von <script> bereit, um die Kulturauswahl des Benutzers mit dem lokalen Speicher des Browsers abzurufen und festzulegen:

<script>
  window.blazorCulture = {
    get: () => window.localStorage['BlazorCulture'],
    set: (value) => window.localStorage['BlazorCulture'] = value
  };
</script>

Hinweis

Das Beispiel oben verunreinigt den Client mit globalen Funktionen. Einen besseren Ansatz für Produktions-Apps finden Sie unter JavaScript-Isolation in JavaScript-Modulen.

Fügen Sie am Anfang der System.Globalization-Datei die Namespaces für Microsoft.JSInterop und Program hinzu:

using System.Globalization;
using Microsoft.JSInterop;

Entfernen Sie die folgende Zeile:

- await builder.Build().RunAsync();

Ersetzen Sie die obige Zeile durch den folgenden Code. Der Code fügt den Lokalisierungsdienst von Blazor mit AddLocalization zur Dienstsammlung der App hinzu und verwendet JS-Interop, um in JS aufzurufen und die Kulturauswahl des Benutzers aus dem lokalen Speicher abzurufen. Wenn der lokale Speicher keine Kultur für den Benutzer enthält, legt der Code US-Englisch (en-US) als Standardwert fest.

builder.Services.AddLocalization();

var host = builder.Build();

const string defaultCulture = "en-US";

var js = host.Services.GetRequiredService<IJSRuntime>();
var result = await js.InvokeAsync<string>("blazorCulture.get");
var culture = CultureInfo.GetCultureInfo(result ?? defaultCulture);

if (result == null)
{
    await js.InvokeVoidAsync("blazorCulture.set", defaultCulture);
}

CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

await host.RunAsync();

Hinweis

Die folgende CultureSelector-Komponente zeigt, wie die folgenden Aktionen durchgeführt werden:

Festlegen der Kulturauswahl von Benutzer*innen über JS-Interop auf einen lokalen Browserspeicher
Erneutes Laden der angeforderten Komponente (forceLoad: true), die die aktualisierte Kultur verwendet

CultureSelector.razor:

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select @bind="selectedCulture" @bind:after="ApplySelectedCultureAsync">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task ApplySelectedCultureAsync()
    {
        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture!.Name);

            Navigation.NavigateTo(Navigation.Uri, forceLoad: true);
        }
    }
}

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select value="@selectedCulture" @onchange="HandleSelectedCultureChanged">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task HandleSelectedCultureChanged(ChangeEventArgs args)
    {
        selectedCulture = CultureInfo.GetCultureInfo((string)args.Value!);

        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture!.Name);

            Navigation.NavigateTo(Navigation.Uri, forceLoad: true);
        }
    }
}

Hinweis

Weitere Informationen zu IJSInProcessRuntime finden Sie unter Aufrufen von JavaScript-Funktionen über .NET-Methoden in ASP.NET CoreBlazor.

Fügen Sie im schließenden Tag des </main>-Elements in der Komponente MainLayout (MainLayout.razor) die Komponente CultureSelector hinzu:

<article class="bottom-row px-4">
    <CultureSelector />
</article>

Verwenden Sie die Im Abschnitt CultureExample1 gezeigte -Komponente, um zu untersuchen, wie das obige Beispiel funktioniert.

Dynamisches Festlegen der serverseitigen Kultur durch Benutzereinstellung

Beispiele für Speicherorte, an denen eine App die Einstellungen von Benutzer*innen speichern kann, sind der lokale Speicher des Browsers (bei clientseitigen Szenarios üblich), in einem cookie oder einer Datenbank für die Lokalisierung (bei serverseitigen Szenarios üblich) oder in einem externen Dienst, der an eine externe Datenbank angefügt und über eine Web-API zugänglich ist. Das folgende Beispiel veranschaulicht, wie ein Lokalisierungs-cookie verwendet wird.

Hinweis

Im folgenden Beispiel wird davon ausgegangen, dass die Anwendung globale Interaktivität annimmt, indem das interaktive serverseitige Rendering (interaktive SSR) auf der Routes-Komponente in der App-Komponente (Components/App.razor) angegeben wird:

<Routes @rendermode="InteractiveServer" />

Wenn die App Interaktivität pro Seite/Komponente verwendet, lesen Sie die Hinweise am Ende dieses Abschnitts, um die Rendermodi der Komponenten des Beispiels zu ändern.

Fügen Sie der App das Paket Microsoft.Extensions.Localization hinzu.

Hinweis

Serverseitige Apps werden über Lokalisierungsmiddleware lokalisiert. Fügen Sie der App mit AddLocalization Lokalisierungsdienste hinzu.

In der Datei Program:

builder.Services.AddLocalization();

Legen Sie die standardmäßigen und unterstützten Kulturen der App mit RequestLocalizationOptions fest.

Platzieren Sie vor dem Aufruf an MapRazorComponents in der Anforderungsverarbeitungspipeline den folgenden Code:

Nachdem das Routing-Middleware (UseRouting) zur Anforderungspipeline hinzugefügt wurde, platzieren Sie den folgenden Code:

var supportedCultures = new[] { "en-US", "es-CR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Informationen zur Anordnung der Lokalisierungsmiddleware in der Middlewarepipeline finden Sie unter ASP.NET Core-Middleware.

Im folgenden Beispiel wird veranschaulicht, wie die aktuelle Kultur in einem cookie festgelegt werden kann, das von der Lokalisierungsmiddleware gelesen werden kann.

Die folgenden Namespaces sind für die App-Komponente erforderlich:

Fügen Sie folgendes am Anfang der App-Komponentendatei (Components/App.razor) hinzu:

@using System.Globalization
@using Microsoft.AspNetCore.Localization

Fügen Sie den folgenden @code-Block am Ende der App-Komponentendatei hinzu:

@code {
    [CascadingParameter]
    public HttpContext? HttpContext { get; set; }

    protected override void OnInitialized()
    {
        HttpContext?.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(
                    CultureInfo.CurrentCulture,
                    CultureInfo.CurrentUICulture)));
    }
}

Änderungen an der Pages/_Host.cshtml-Datei erfordern die folgenden Namespaces:

Fügen Sie der Datei die folgende Zeile hinzu:

@using System.Globalization
@using Microsoft.AspNetCore.Localization
@{
    this.HttpContext.Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(
            new RequestCulture(
                CultureInfo.CurrentCulture,
                CultureInfo.CurrentUICulture)));
}

Informationen zur Anordnung der Lokalisierungsmiddleware in der Middlewarepipeline finden Sie unter ASP.NET Core-Middleware.

Befolgen Sie die folgenden Schritte, wenn die App nicht für die Verarbeitung von Controlleraktionen konfiguriert ist:

Fügen Sie MVC-Dienste hinzu, indem Sie AddControllers für die Dienstsammlung in der Program-Datei aufrufen:
```
builder.Services.AddControllers();
```
Fügen Sie Controllerendpunktrouting in der Program-Datei hinzu, indem Sie MapControllers in IEndpointRouteBuilder aufrufen (app):
```
app.MapControllers();
```

Um eine Benutzeroberfläche bereitzustellen, die Benutzern das Auswählen einer Kultur ermöglicht, wird eine umleitungsbasierte Vorgehensweise mit einem Lokalisierungs-cookie empfohlen. Die App behält die vom Benutzer ausgewählte Kultur mithilfe einer Umleitung an einen Controller bei. Der Controller legt die ausgewählte Kultur des Benutzers mit einem cookie fest und leitet den Benutzer wieder an den ursprünglichen URI weiter. Der Prozess ist ähnelt dem Ablauf in einer Web-App, wenn ein Benutzer versucht, auf eine sichere Ressource zuzugreifen: der Benutzer wird an eine Anmeldeseite umgeleitet und dann wieder zur ursprünglichen Ressource geleitet.

Controllers/CultureController.cs:

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult Set(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

Warnung

Verwenden Sie das LocalRedirect Aktionsergebnis wie im vorherigen Beispiel gezeigt, um offene Umleitungsangriffe zu verhindern. Weitere Informationen finden Sie unter Verhindern von Open-Redirect-Angriffen in ASP.NET Core.

Die folgende CultureSelector-Komponente zeigt, wie Sie die Set-Methode von CultureController mit der neuen Kultur aufrufen. Die Komponente wird zur Verwendung in der App im Shared-Ordner abgelegt.

CultureSelector.razor:

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select @bind="selectedCulture" @bind:after="ApplySelectedCultureAsync">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task ApplySelectedCultureAsync()
    {
        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

            Navigation.NavigateTo(
                $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                forceLoad: true);
        }
    }
}

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select value="@selectedCulture" @onchange="HandleSelectedCultureChanged">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task HandleSelectedCultureChanged(ChangeEventArgs args)
    {
        selectedCulture = CultureInfo.GetCultureInfo((string)args.Value!);

        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

            Navigation.NavigateTo(
                $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                forceLoad: true);
        }
    }
}

Fügen Sie die CultureSelector-Komponente der MainLayout-Komponente hinzu. Platzieren Sie das folgende Markup innerhalb des schließenden </main>-Tags in der Components/Layout/MainLayout.razor-Datei:

Fügen Sie die CultureSelector-Komponente der MainLayout-Komponente hinzu. Platzieren Sie das folgende Markup innerhalb des schließenden </main>-Tags in der Shared/MainLayout.razor-Datei:

<article class="bottom-row px-4">
    <CultureSelector />
</article>

Verwenden Sie die Im Abschnitt CultureExample1 gezeigte -Komponente, um zu untersuchen, wie das obige Beispiel funktioniert.

Im vorherigen Beispiel wird davon ausgegangen, dass die App globale Interaktivität verwendet, indem sie den interaktiven Server-Rendermodus für die Routes-Komponente in der App-Komponente (Components/App.razor) angibt:

<Routes @rendermode="InteractiveServer" />

Wenn die App Interaktivität pro Seite/Komponente verwendet, nehmen Sie die folgenden Änderungen vor:

Fügen Sie den Rendermodus Interaktiver Server oben in der Komponentendatei CultureExample1 hinzu (Components/Pages/CultureExample1.razor):
```
@rendermode InteractiveServer
```
Wenden Sie im Hauptlayout der App (Components/Layout/MainLayout.razor) den Rendermodus Interaktiver Server auf die Komponente CultureSelector an:
```
<CultureSelector @rendermode="InteractiveServer" />
```

Die Kultur in einem Blazor Web App dynamisch nach der Bevorzugten Sprache des Benutzers festlegen

Dieser Abschnitt gilt für Blazor Web Apps, die die Auto-Interaktivität (Server und WebAssembly) übernehmen.

Beispiele für Orte, an denen eine App die Benutzerpräferenz speichern könnte, umfassen den lokalen Speicher des Browsers (häufig für clientseitige Szenarien), in einer Lokalisierung cookie oder Datenbank (häufig für serverseitige Szenarien), sowohl lokaler Speicher als auch eine Lokalisierung cookie (Blazor Web Apps mit Server- und WebAssembly-Komponenten), oder in einem externen Dienst, der an eine externe Datenbank angeschlossen ist und über eine Web-API zugänglich ist. Im folgenden Beispiel wird veranschaulicht, wie Sie den lokalen Browserspeicher für clientseitige gerenderte Komponenten (CSR) und eine Lokalisierung cookie für serverseitig gerenderte Komponenten (SSR) verwenden.

Aktualisierungen des `.Client` Projekts

Microsoft.Extensions.Localization-Paket zum .Client Projekt hinzufügen.

Hinweis

Legen Sie die BlazorWebAssemblyLoadAllGlobalizationData-Eigenschaft auf true in der .ClientProjektdatei fest:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Fügen Namespaces für System.Globalization und Microsoft.JSInterop am Anfang der .Client-Projektdatei Program hinzu:

using System.Globalization;
using Microsoft.JSInterop;

Entfernen Sie die folgende Zeile:

- await builder.Build().RunAsync();

builder.Services.AddLocalization();

var host = builder.Build();

const string defaultCulture = "en-US";

var js = host.Services.GetRequiredService<IJSRuntime>();
var result = await js.InvokeAsync<string>("blazorCulture.get");
var culture = CultureInfo.GetCultureInfo(result ?? defaultCulture);

if (result == null)
{
    await js.InvokeVoidAsync("blazorCulture.set", defaultCulture);
}

CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

await host.RunAsync();

Hinweis

Fügen Sie folgende CultureSelector Komponente dem .Client Projekt hinzu.

Die Komponente funktioniert mit den folgenden Ansätzen für SSR- oder CSR-Komponenten:

Der Anzeigename jeder verfügbaren Kultur in der Dropdownliste wird von einem Wörterbuch bereitgestellt, da clientseitige Globalisierungsdaten lokalisierten Text von Kulturanzeigenamen enthalten, die von serverseitigen Globalisierungsdaten bereitgestellt werden. So wird beispielsweise die serverseitige Lokalisierung English (United States) angezeigt, wenn en-US es sich um Kultur handelt und Ingles () bei Verwendung einer anderen Kultur. Da die Lokalisierung der Kulturanzeigenamen Blazor WebAssembly globalisierungsbedingt nicht verfügbar ist, ist der Anzeigename für Englisch (USA) auf dem Client für jede geladene Kultur einfach en-US. Durch die Verwendung eines Benutzerwörterbuchs kann die Komponente zumindest vollständige englische Kulturnamen anzeigen.
Wenn der/die Benutzer*in die Kultur ändert, JS legt Interop die Kultur im lokalen Browserspeicher fest, und eine Controlleraktion aktualisiert die Lokalisierung cookie mit der Kultur. Der Controller wird der App später im Abschnitt Server-Projektaktualisierungen hinzugefügt.

Pages/CultureSelector.razor:

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select @bind="@selectedCulture" @bind:after="ApplySelectedCultureAsync">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@cultureDict[culture.Name]</option>
            }
        </select>
    </label>
</p>

@code
{
    private Dictionary<string, string> cultureDict = 
        new()
        {
            { "en-US", "English (United States)" },
            { "es-CR", "Spanish (Costa Rica)" }
        };

    private CultureInfo[] supportedCultures = 
        [ 
            new CultureInfo("en-US"), 
            new CultureInfo("es-CR"),
        ];

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task ApplySelectedCultureAsync()
    {
        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture!.Name);

            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

            Navigation.NavigateTo(
                $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                forceLoad: true);
        }
    }
}

Fügen Sie in der .Client Datei des _Imports Projekts (_Imports.razor) den Namespace für die Komponenten im Ordner Pages hinzu, und aktualisieren Sie den Namespace so, dass er dem Namespace Ihres .Client Projekts entspricht:

@using BlazorSample.Client.Pages

Hinweis

Weitere Informationen zu IJSInProcessRuntime finden Sie unter Aufrufen von JavaScript-Funktionen über .NET-Methoden in ASP.NET CoreBlazor.

Fügen Sie im .Client-Projekt die CultureSelector-Komponente zur MainLayout-Komponente hinzu. Platzieren Sie das folgende Markup innerhalb des schließenden </main>-Tags in der Layout/MainLayout.razor-Datei:

<article class="bottom-row px-4">
    <CultureSelector @rendermode="InteractiveAuto" />
</article>

Platzieren Sie im .Client Projekt die folgende CultureClient Komponente, um zu untersuchen, wie Globalisierung für CSR-Komponenten funktioniert.

Pages/CultureClient.razor:

@page "/culture-client"
@rendermode InteractiveWebAssembly
@using System.Globalization

<PageTitle>Culture Client</PageTitle>

<h1>Culture Client</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Rendered values</h2>

<ul>
    <li><b>Date</b>: @dt</li>
    <li><b>Number</b>: @number.ToString("N2")</li>
</ul>

<h2><code>&lt;input&gt;</code> elements that don't set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.CurrentCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input @bind="number" /></label></li>
</ul>

<h2><code>&lt;input&gt;</code> elements that set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.InvariantCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input type="date" @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input type="number" @bind="number" /></label></li>
</ul>

@code {
    private DateTime dt = DateTime.Now;
    private double number = 1999.69;
}

Platzieren Sie im .Client Projekt die folgende CultureServer Komponente, um zu untersuchen, wie Globalisierung für SSR-Komponenten funktioniert.

Pages/CultureServer.razor:

@page "/culture-server"
@rendermode InteractiveServer
@using System.Globalization

<PageTitle>Culture Server</PageTitle>

<h1>Culture Server</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Rendered values</h2>

<ul>
    <li><b>Date</b>: @dt</li>
    <li><b>Number</b>: @number.ToString("N2")</li>
</ul>

<h2><code>&lt;input&gt;</code> elements that don't set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.CurrentCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input @bind="number" /></label></li>
</ul>

<h2><code>&lt;input&gt;</code> elements that set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.InvariantCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input type="date" @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input type="number" @bind="number" /></label></li>
</ul>

@code {
    private DateTime dt = DateTime.Now;
    private double number = 1999.69;
}

Verwenden Sie die CultureExample1-Komponente, die im Abschnitt Demonstrationskomponente gezeigt wird, um zu untersuchen, wie die Globalisierung für eine Komponente funktioniert, die den globalen Rendermodus Auto erbt. Fügen Sie die CultureExample1-Komponente zum Ordner .Client des Projekts Pages hinzu.

Fügen Sie die Komponenten CultureClient, CultureServer und CultureExample1 zur Navigation in der Seitenleiste in Layout/NavMenu.razor hinzu:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-server">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Server)
    </NavLink>
</div>
<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-client">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Client)
    </NavLink>
</div>
<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-example-1">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Auto)
    </NavLink>
</div>

Serverprojektaktualisierungen

Fügen Sie das Microsoft.Extensions.Localization Paket dem Serverprojekt hinzu.

Hinweis

Serverseitige Apps werden über Lokalisierungsmiddleware lokalisiert. Fügen Sie der App mit AddLocalization Lokalisierungsdienste hinzu.

In der Datei des Serverprojekts, Program in der Dienste registriert sind:

builder.Services.AddLocalization();

Legen Sie die standardmäßigen und unterstützten Kulturen der App mit RequestLocalizationOptions fest.

Platzieren Sie vor dem Aufruf an MapRazorComponents in der Anforderungsverarbeitungspipeline den folgenden Code:

var supportedCultures = new[] { "en-US", "es-CR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Im folgenden Beispiel wird veranschaulicht, wie die aktuelle Kultur in einem cookie festgelegt werden kann, das von der Lokalisierungsmiddleware gelesen werden kann.

Die folgenden Namespaces sind für die App-Komponente erforderlich:

Fügen Sie folgendes am Anfang der App-Komponentendatei (Components/App.razor) hinzu:

@using System.Globalization
@using Microsoft.AspNetCore.Localization

Die Kultur der App für clientseitiges Rendering (CSR) wird mithilfe der API des Blazor-Frameworks festgelegt. Die Kulturauswahl eines Benutzers/einer Benutzerin kann bei CSR-Komponenten im lokalen Browserspeicher gespeichert werden.

Nach dem Blazor-Tag von <script> bieten Sie JS-Funktionen an, um die Kulturauswahl des Benutzers mit dem lokalen Speicher des Browsers abzurufen und festzulegen:

<script>
  window.blazorCulture = {
    get: () => window.localStorage['BlazorCulture'],
    set: (value) => window.localStorage['BlazorCulture'] = value
  };
</script>

Hinweis

Das Beispiel oben verunreinigt den Client mit globalen Funktionen. Einen besseren Ansatz für Produktions-Apps finden Sie unter JavaScript-Isolation in JavaScript-Modulen.

Fügen Sie den folgenden @code-Block am Ende der App-Komponentendatei hinzu:

@code {
    [CascadingParameter]
    public HttpContext? HttpContext { get; set; }

    protected override void OnInitialized()
    {
        HttpContext?.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(
                    CultureInfo.CurrentCulture,
                    CultureInfo.CurrentUICulture)));
    }
}

Wenn das Serverprojekt nicht für die Verarbeitung von Controlleraktionen konfiguriert ist:

Fügen Sie MVC-Dienste hinzu, indem Sie AddControllers für die Dienstsammlung in der Program-Datei aufrufen:
```
builder.Services.AddControllers();
```
Fügen Sie Controllerendpunktrouting in der Program-Datei hinzu, indem Sie MapControllers in IEndpointRouteBuilder aufrufen (app):
```
app.MapControllers();
```

Um Benutzer*innen die Auswahl einer Kultur für SSR-Komponenten zu ermöglichen, verwenden Sie eine umleitungsbasierte Vorgehensweise mit einer Lokalisierungcookie. Die App behält die vom Benutzer ausgewählte Kultur mithilfe einer Umleitung an einen Controller bei. Der Controller legt die ausgewählte Kultur des Benutzers mit einem cookie fest und leitet den Benutzer wieder an den ursprünglichen URI weiter. Der Prozess ist ähnelt dem Ablauf in einer Web-App, wenn ein Benutzer versucht, auf eine sichere Ressource zuzugreifen: der Benutzer wird an eine Anmeldeseite umgeleitet und dann wieder zur ursprünglichen Ressource geleitet.

Controllers/CultureController.cs:

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult Set(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

Warnung

Interaktive Auto-Komponenten

Die Anleitung in diesem Abschnitt funktioniert auch für Komponenten in Apps, die das Rendern pro Seite/Komponente übernehmen und den interaktiven automatischen Rendermodus angeben:

@rendermode InteractiveAuto

Lokalisierung

Wenn die App die dynamische Kulturauswahl noch nicht unterstützt, fügen Sie der App das Paket Microsoft.Extensions.Localization hinzu.

Hinweis

Clientseitige Lokalisierung

Legen Sie die BlazorWebAssemblyLoadAllGlobalizationData-Eigenschaft in der Projektdatei der App (true) auf .csproj fest:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Fügen Sie in der Program-Datei den Namespace für System.Globalization am Anfang hinzu:

using System.Globalization;

Fügen Sie den Lokalisierungsdienst von Blazor mit AddLocalization der Dienstsammlung der App hinzu:

builder.Services.AddLocalization();

Serverseitige Lokalisierung

Verwenden Sie Lokalisierungsmiddleware, um die Kultur der App festzulegen.

Wenn die App die dynamische Kulturauswahl noch nicht unterstützt, gehen Sie folgendermaßen vor:

Fügen Sie der App mit AddLocalization Lokalisierungsdienste hinzu.
Legen Sie die Standardkulturen und die unterstützten Kulturen der App in der Program-Datei fest. Im folgenden Beispiel werden unterstützte Kulturen für US-Englisch und Costa Rica-Spanisch konfiguriert.

builder.Services.AddLocalization();

Platzieren Sie das Middleware zur Anforderungslokalisierung vor jeder Middleware, die möglicherweise die Anforderungskultur überprüft. Im Allgemeinen platzieren Sie die Middleware unmittelbar vor dem Aufruf von MapRazorComponents:

Unmittelbar nachdem die Routing-Middleware (UseRouting) zur Verarbeitungspipeline hinzugefügt wurde:

var supportedCultures = new[] { "en-US", "es-CR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Informationen zur Anordnung der Lokalisierungsmiddleware in der Middlewarepipeline finden Sie unter ASP.NET Core-Middleware.

Fügen Sie der App mit AddLocalization Lokalisierungsdienste hinzu.
Geben Sie die standardmäßigen und unterstützten Kulturen der App in Startup.Configure (Startup.cs) fest. Im folgenden Beispiel werden unterstützte Kulturen für US-Englisch und Costa Rica-Spanisch konfiguriert.

In Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

In Startup.Configure unmittelbar nachdem das Routing-Middleware (UseRouting) zur Verarbeitungspipeline hinzugefügt wurde:

var supportedCultures = new[] { "en-US", "es-CR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Informationen zur Anordnung der Lokalisierungsmiddleware in der Middlewarepipeline von Startup.Configure finden Sie unter ASP.NET Core-Middleware.

Wenn die App Ressourcen basierend auf der Speicherung einer Kultureinstellung eines Benutzers lokalisieren soll, verwenden Sie eine cookie für die Lokalisierungskultur. Durch Verwendung eines cookie wird sichergestellt, wird sichergestellt, dass die WebSocket-Verbindung die Kultur ordnungsgemäß weitergeben kann. Wenn die Lokalisierungsschemas auf dem URL-Pfad oder der Abfragezeichenfolge basieren, kann das Schema möglicherweise nicht mit WebSockets funktionieren, wodurch das Beibehalten der Kultur fehlschlägt. Daher wird empfohlen, ein cookie für die Lokalisierungskultur zu verwenden. Im Abschnitt Dynamisches Festlegen der serverseitigen Kultur durch Benutzereinstellung dieses Artikels finden Sie einen Razor-Beispielausdruck, der die Kulturauswahl der Benutzer*innen speichert.

Beispiel für lokalisierte Ressourcen

Das Beispiel für lokalisierte Ressourcen in diesem Abschnitt funktioniert mit den obigen Beispielen in diesem Artikel, in denen die unterstützten Kulturen der App Englisch (en) als Standardgebietsschema und Spanisch (es) als vom Benutzer auswählbares oder vom Browser angegebenes alternatives Gebietsschema sind.

Erstellen Sie eine Ressourcendatei für jedes Gebietsschema. Im folgenden Beispiel werden Ressourcen für eine Greeting-Zeichenfolge auf Englisch und Spanisch erstellt:

Englisch (en): Hello, World!
Spanisch (es): ¡Hola, Mundo!

Hinweis

Die folgende Ressourcendatei kann in Visual Studio hinzugefügt werden, indem Sie mit der rechten Maustaste auf den Pages Ordner klicken und Hinzufügen>Neues Element>Ressourcendatei auswählen. Nennen Sie die Datei CultureExample2.resx. Geben Sie Daten für einen neuen Eintrag an, wenn der Editor angezeigt wird. Legen Sie Name auf Greeting und Wert auf Hello, World! fest. Speichern Sie die Datei.

Wenn Sie Visual Studio Code verwenden, empfehlen wir die Installation des ResX-Viewers und -Editors von Tim Heuer. Fügen Sie eine leere Datei vom Typ CultureExample2.resx zum Ordner Pages hinzu. Die Erweiterung übernimmt automatisch die Verwaltung der Datei auf der Benutzeroberfläche. Wählen Sie die Schaltfläche Neue Ressource hinzufügen aus. Befolgen Sie die Anweisungen, um einen Eintrag für Greeting (Schlüssel), Hello, World! (Wert) und None (Kommentar) hinzuzufügen. Speichern Sie die Datei. Wenn Sie die Datei schließen und erneut öffnen, wird die Ressource Greeting angezeigt.

Tim Heuers ResX Viewer und Editor wird nicht von Microsoft verwaltet oder gepflegt und fällt nicht unter eine Microsoft-Supportvereinbarung oder Lizenzbedingungen.

Im Folgenden wird eine typische Ressourcendatei veranschaulicht. Sie können Ressourcendateien manuell in den Ordner Pages der App einfügen, wenn Sie keine integrierten Tools mit einer integrierten Entwicklungsumgebung (Integrated Development Environment, IDE) wie dem integrierten Ressourcendatei-Editor von Visual Studio oder Visual Studio Code mit einer Erweiterung zum Erstellen und Bearbeiten von Ressourcendateien verwenden möchten.

Pages/CultureExample2.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
    <xsd:element name="root" msdata:IsDataSet="true">
      <xsd:complexType>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="metadata">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" />
              </xsd:sequence>
              <xsd:attribute name="name" use="required" type="xsd:string" />
              <xsd:attribute name="type" type="xsd:string" />
              <xsd:attribute name="mimetype" type="xsd:string" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="assembly">
            <xsd:complexType>
              <xsd:attribute name="alias" type="xsd:string" />
              <xsd:attribute name="name" type="xsd:string" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="data">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="resheader">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" />
            </xsd:complexType>
          </xsd:element>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
  <resheader name="resmimetype">
    <value>text/microsoft-resx</value>
  </resheader>
  <resheader name="version">
    <value>2.0</value>
  </resheader>
  <resheader name="reader">
    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <resheader name="writer">
    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <data name="Greeting" xml:space="preserve">
    <value>Hello, World!</value>
  </data>
</root>

Hinweis

Die folgende Ressourcendatei kann in Visual Studio hinzugefügt werden, indem Sie mit der rechten Maustaste auf den Pages Ordner klicken und Hinzufügen>Neues Element>Ressourcendatei auswählen. Nennen Sie die Datei CultureExample2.es.resx. Geben Sie Daten für einen neuen Eintrag an, wenn der Editor angezeigt wird. Legen Sie Name auf Greeting und Wert auf ¡Hola, Mundo! fest. Speichern Sie die Datei.

Wenn Sie Visual Studio Code verwenden, empfehlen wir die Installation des ResX-Viewers und -Editors von Tim Heuer. Fügen Sie eine leere Datei vom Typ CultureExample2.resx zum Ordner Pages hinzu. Die Erweiterung übernimmt automatisch die Verwaltung der Datei auf der Benutzeroberfläche. Wählen Sie die Schaltfläche Neue Ressource hinzufügen aus. Befolgen Sie die Anweisungen, um einen Eintrag für Greeting (Schlüssel), ¡Hola, Mundo! (Wert) und None (Kommentar) hinzuzufügen. Speichern Sie die Datei. Wenn Sie die Datei schließen und erneut öffnen, wird die Ressource Greeting angezeigt.

Pages/CultureExample2.es.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
    <xsd:element name="root" msdata:IsDataSet="true">
      <xsd:complexType>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="metadata">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" />
              </xsd:sequence>
              <xsd:attribute name="name" use="required" type="xsd:string" />
              <xsd:attribute name="type" type="xsd:string" />
              <xsd:attribute name="mimetype" type="xsd:string" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="assembly">
            <xsd:complexType>
              <xsd:attribute name="alias" type="xsd:string" />
              <xsd:attribute name="name" type="xsd:string" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="data">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="resheader">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" />
            </xsd:complexType>
          </xsd:element>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
  <resheader name="resmimetype">
    <value>text/microsoft-resx</value>
  </resheader>
  <resheader name="version">
    <value>2.0</value>
  </resheader>
  <resheader name="reader">
    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <resheader name="writer">
    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <data name="Greeting" xml:space="preserve">
    <value>¡Hola, Mundo!</value>
  </data>
</root>

Die folgende Komponente veranschaulicht die Verwendung der lokalisierten Greeting-Zeichenfolge mit IStringLocalizer<T>. Das Razor-Markup @Loc["Greeting"] im folgenden Beispiel lokalisiert die Zeichenfolge, die an den Greeting-Wert gebunden ist, der in den vorherigen Ressourcendateien festgelegt ist.

Fügen Sie den Namespace für Microsoft.Extensions.Localization zur _Imports.razor-Datei der App hinzu:

@using Microsoft.Extensions.Localization

CultureExample2.razor:

@page "/culture-example-2"
@using System.Globalization
@inject IStringLocalizer<CultureExample2> Loc

<h1>Culture Example 2</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Greeting</h2>

<p>
    @Loc["Greeting"]
</p>

<p>
    @greeting
</p>

@code {
    private string? greeting;

    protected override void OnInitialized()
    {
        greeting = Loc["Greeting"];
    }
}

Fügen Sie der Navigation in der CultureExample2-Komponente (NavMenu) optional ein Menüelement für die NavMenu.razor-Komponente hinzu.

Referenzquelle für WebAssembly-Kulturanbieter

Um ein besseres Verständnis dafür zu erlangen, wie das Blazor-Framework die Lokalisierung verarbeitet, sehen Sie sich die WebAssemblyCultureProvider-Klasse in der ASP.NET Core-Referenzquelle an.

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

Gemeinsame Ressourcen

Gehen Sie wie folgt vor, um freigegebene Ressourcen für die Lokalisierung zu erstellen:

Vergewissern Sie sich, dass das Microsoft.Extensions.Localization-Paket vom Projekt referenziert wird.

Hinweis

Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.
Vergewissern Sie sich, dass der Microsoft.Extensions.Localization-Namespace über einen Eintrag in der Datei Razor des Projekts für die Komponenten _Imports verfügbar ist.
```
@using Microsoft.Extensions.Localization
```
Erstellen Sie eine Dummyklasse mit einem beliebigen Klassennamen. Im folgenden Beispiel:
- Die App verwendet den BlazorSample-Namespace, und Lokalisierungsressourcen nutzen den BlazorSample.Localization-Namespace.
- Die Dummyklasse heißt SharedResource.
- Die Klassendatei wird in einem Ordner vom Typ Localization im Stammverzeichnis der App abgelegt.
Hinweis

Verwenden Sie keine automatisch generierte Designerdatei (z. B. SharedResources.Designer.cs). Die Dummy-Klasse soll als gemeinsame Ressourcenklasse fungieren. Das Vorhandensein einer Designerdatei führt zu einem Namespacekonflikt.

Localization/SharedResource.cs:
```
namespace BlazorSample.Localization;

public class SharedResource
{
}
```
Erstellen Sie die freigegebenen Ressourcendateien mit der BuildaktionEmbedded resource. Im folgenden Beispiel:
- Die Dateien werden im Ordner Localization mit der Dummyklasse SharedResource (Localization/SharedResource.cs) abgelegt.
- Benennen Sie die Ressourcendateien so, dass sie dem Namen der Dummyklasse entsprechen. Die folgenden Beispieldateien enthalten eine Standardlokalisierungsdatei und eine Datei für die spanische Lokalisierung (es).
- Localization/SharedResource.resx
- Localization/SharedResource.es.resx
Warnung

Wenn Sie dem Ansatz in diesem Abschnitt folgen, können Sie nicht gleichzeitig LocalizationOptions.ResourcesPath festlegen und IStringLocalizerFactory.Create verwenden, um Ressourcen zu laden.
Um auf die Dummyklasse für ein eingefügtes IStringLocalizer<T>-Element in einer Razor-Komponente zu verweisen, geben Sie entweder eine @using-Anweisung für den Lokalisierungsnamespace an, oder fügen Sie den Lokalisierungsnamespace in den Dummyklassenverweis ein. In den folgenden Beispielen:
- Im ersten Beispiel wird der Localization-Namespace für die Dummyklasse SharedResource mit einer @using-Anweisung angegeben.
- Im zweiten Beispiel wird der Namespace der SharedResource-Dummyklasse explizit angegeben.
Befolgen Sie in einer Razor-Komponente einen der folgenden Ansätze:
```
@using Localization
@inject IStringLocalizer<SharedResource> Loc
```
```
@inject IStringLocalizer<Localization.SharedResource> Loc
```

Weitere Informationen finden Sie unter Globalisierung und Lokalisierung in ASP.NET Core.

Standortüberschreibung mithilfe des Bereichs „Sensoren“ in den Entwicklertools

Wenn Sie die Standortüberschreibung mithilfe des Bereichs Sensoren in den Entwicklertools von Google Chrome oder Microsoft Edge verwenden, wird die Fallbacksprache nach dem Vorabrendering zurückgesetzt. Vermeiden Sie das Festlegen der Sprache mithilfe des Bereichs Sensoren beim Testen. Legen Sie die Sprache mithilfe der Spracheinstellungen des Browsers fest.

Weitere Informationen finden Sie unter Blazor. Die Lokalisierung funktioniert nicht mit InteractiveServer (dotnet/aspnetcore #53707).

Teilen über

Globalisierung und Lokalisierung in ASP.NET Core Blazor

Globalisierung und Lokalisierung

Globalisierung

Unterstützung der .NET-Globalisierung und internationaler Komponenten für Unicode (Blazor WebAssembly)

Invariante Globalisierung

Zeitzoneninformationen

Demokomponente

Dynamisches Festlegen der Kultur über den Accept-Language-Header

Statisches Festlegen der clientseitigen Kultur

Statisches Festlegen der serverseitigen Kultur

Dynamisches Festlegen der clientseitigen Kultur durch Benutzereinstellung

Dynamisches Festlegen der serverseitigen Kultur durch Benutzereinstellung

Die Kultur in einem Blazor Web App dynamisch nach der Bevorzugten Sprache des Benutzers festlegen

Aktualisierungen des .Client Projekts

Serverprojektaktualisierungen

Interaktive Auto-Komponenten

Lokalisierung

Clientseitige Lokalisierung

Serverseitige Lokalisierung

Beispiel für lokalisierte Ressourcen

Referenzquelle für WebAssembly-Kulturanbieter

Gemeinsame Ressourcen

Standortüberschreibung mithilfe des Bereichs „Sensoren“ in den Entwicklertools

Zusätzliche Ressourcen

Feedback

Zusätzliche Ressourcen

Dynamisches Festlegen der Kultur über den `Accept-Language`-Header

Aktualisierungen des `.Client` Projekts