Globalisierung und Lokalisierung in ASP.NET Core BlazorASP.NET Core Blazor globalization and localization

Razor-Komponenten können Benutzern mit verschiedenen Kulturen und Sprachen zur Verfügung gestellt werden.Razor components can be made accessible to users in multiple cultures and languages. Die folgenden Szenarios zur Globalisierung und Lokalisierung von .NET sind verfügbar:The following .NET globalization and localization scenarios are available:

  • .NET-Ressourcensystem.NET's resources system
  • Kulturspezifische Zahlen- und DatumsformatierungCulture-specific number and date formatting

Derzeit werden Lokalisierungsszenarios für ASP.NET Core eingeschränkt unterstützt:A limited set of ASP.NET Core's localization scenarios are currently supported:

Weitere Informationen finden Sie unter Globalisierung und Lokalisierung in ASP.NET Core.For more information, see Globalisierung und Lokalisierung in ASP.NET Core.

GlobalisierungGlobalization

Die @bind-Funktionalität von Blazor führt die Formatierung durch und analysiert Werte, um die Anzeige an die Kultur des jeweiligen Benutzers anzupassen.Blazor's @bind functionality performs formats and parses values for display based on the user's current culture.

Der Zugriff auf die aktuelle Kultur kann über die System.Globalization.CultureInfo.CurrentCulture-Eigenschaft erfolgen.The current culture can be accessed from the System.Globalization.CultureInfo.CurrentCulture property.

CultureInfo.InvariantCulture wird für die folgenden Feldtypen verwendet (<input type="{TYPE}" />):CultureInfo.InvariantCulture is used for the following field types (<input type="{TYPE}" />):

  • date
  • number

Diese Feldtypen:The preceding field types:

  • werden basierend auf ihren entsprechenden browserbasierten Formatierungsregeln angezeigt.Are displayed using their appropriate browser-based formatting rules.
  • können keinen Freiformtext enthalten.Can't contain free-form text.
  • bieten Benutzerinteraktionsmerkmale basierend auf der Implementierung des Browsers.Provide user interaction characteristics based on the browser's implementation.

Die folgenden Feldtypen verfügen über spezifische Formatierungsanforderungen und werden derzeit nicht von Blazor unterstützt, weil sie von keinem der gängigen Browser unterstützt werden:The following field types have specific formatting requirements and aren't currently supported by Blazor because they aren't supported by all major browsers:

  • datetime-local
  • month
  • week

@bind unterstützt den Parameter @bind:culture, um eine Klasse System.Globalization.CultureInfo für das Analysieren und Formatieren von Werten bereitzustellen.@bind supports the @bind:culture parameter to provide a System.Globalization.CultureInfo for parsing and formatting a value. Vom Festlegen einer Kultur wird abgeraten, wenn die Feldtypen date und number verwendet werden.Specifying a culture isn't recommended when using the date and number field types. date und number verfügen über integrierte Blazor-Unterstützung, die die erforderliche Kultur bereitstellt.date and number have built-in Blazor support that provides the required culture.

LokalisierungLocalization

Blazor WebAssembly

Blazor WebAssembly-Apps legen die Kultur anhand der Spracheinstellungen des Benutzers fest.Blazor WebAssembly apps set the culture using the user's language preference.

Legen Sie in Program.Main CultureInfo.DefaultThreadCurrentCulture und CultureInfo.DefaultThreadCurrentUICulture fest, um die Kultur explizit zu konfigurieren.To explicitly configure the culture, set CultureInfo.DefaultThreadCurrentCulture and CultureInfo.DefaultThreadCurrentUICulture in Program.Main.

Blazor WebAssembly enthält standardmäßig minimale Globalisierungsressourcen, die zum Anzeigen von Werten wie Datums- und Währungsangaben in der Kultur des Benutzers erforderlich sind.By default, Blazor WebAssembly carries minimal globalization resources required to display values, such as dates and currency, in the user's culture. Bei Anwendungen, die eine dynamische Änderung der Kultur unterstützen müssen, sollte BlazorWebAssemblyLoadAllGlobalizationData in der Projektdatei konfiguriert werden:Applications that must support dynamically changing the culture should configure BlazorWebAssemblyLoadAllGlobalizationData in the project file:

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

Blazor WebAssembly kann auch so konfiguriert werden, dass der Start mithilfe einer bestimmten Anwendungskultur erfolgt, indem Optionen an Blazor.start übergeben werden.Blazor WebAssembly can also be configured to launch using a specific application culture using options passed to Blazor.start. Das folgende Beispiel zeigt eine App, die für den Start mit der Kultur en-GB konfiguriert wurde:For instance, the sample below shows an app configured to launch using the en-GB culture:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
  Blazor.start({
    applicationCulture: 'en-GB'
  });
</script>

Der Wert von applicationCulture muss dem Sprachentagformat BCP-47 entsprechen.The value for applicationCulture should conform to the BCP-47 language tag format.

Wenn für die App keine Lokalisierung erforderlich ist, können Sie die App so konfigurieren, dass die invariante Kultur unterstützt wird, die auf der en-US-Kultur basiert:If the app doesn't require localization, you may configure the app to support the invariant culture, which is based on the en-US culture:

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

Mit der IL-Linkerkonfiguration (Intermediate Language, Zwischensprache) für Blazor WebAssembly-Apps werden mit Ausnahme von explizit angeforderten Gebietsschemas alle Internationalisierungsinformationen standardmäßig entfernt.By default, the Intermediate Language (IL) Linker configuration for Blazor WebAssembly apps strips out internationalization information except for locales explicitly requested. Weitere Informationen finden Sie unter Konfigurieren des Linkers für ASP.NET Core Blazor.For more information, see Konfigurieren des Linkers für ASP.NET Core Blazor.

Auch wenn für die meisten Benutzer die standardmäßig von Blazor ausgewählte Kultur möglicherweise ausreichend ist, ziehen Sie in Betracht, Benutzern die Möglichkeit zu geben, ihr bevorzugtes Gebietsschema anzugeben.While the culture that Blazor selects by default might be sufficient for most users, consider offering a way for users to specify their preferred locale. Eine Blazor WebAssembly-Beispiel-App mit Kulturauswahl finden Sie in LocSample, der Beispiel-App für die Lokalisierung.For a Blazor WebAssembly sample app with a culture picker, see the LocSample localization sample app.

Blazor Server

Blazor Server-Apps werden mit Lokalisierungsmiddleware lokalisiert.Blazor Server apps are localized using Localization Middleware. Die Middleware wählt die entsprechende Kultur für Benutzer aus, die Ressourcen von der App anfordern.The middleware selects the appropriate culture for users requesting resources from the app.

Die Kultur kann mit einem der folgenden Ansätze festgelegt werden:The culture can be set using one of the following approaches:

Weitere Informationen und Beispiele finden Sie unter Globalisierung und Lokalisierung in ASP.NET Core.For more information and examples, see Globalisierung und Lokalisierung in ASP.NET Core.

CookieCookies

Ein cookie für die Lokalisierungskultur kann die Kultur des Benutzers beibehalten.A localization culture cookie can persist the user's culture. Die Lokalisierungsmiddleware liest das cookie bei aufeinanderfolgenden Anforderungen, um die Kultur des Benutzers festzulegen.The Localization Middleware reads the cookie on subsequent requests to set the user's culture.

Durch Verwendung eines cookie wird sichergestellt, wird sichergestellt, dass die WebSocket-Verbindung die Kultur ordnungsgemäß weitergeben kann.Use of a cookie ensures that the WebSocket connection can correctly propagate the culture. 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.If localization schemes are based on the URL path or query string, the scheme might not be able to work with WebSockets, thus fail to persist the culture. Daher wird die Verwendung eines cookie für die Lokalisierungskultur empfohlen.Therefore, use of a localization culture cookie is the recommended approach.

Alle Vorgehensweisen können zum Zuweisen einer Kultur verwendet werden, wenn die Kultur in einem Lokalisierungscookie beibehalten wird.Any technique can be used to assign a culture if the culture is persisted in a localization cookie. Wenn die App bereits über ein Lokalisierungsschema für serverseitiges ASP.NET Core verfügt, können Sie die vorhandene Lokalisierungsinfrastruktur der App weiterhin verwenden und das Lokalisierungskulturcookie innerhalb des Schemas der App festlegen.If the app already has an established localization scheme for server-side ASP.NET Core, continue to use the app's existing localization infrastructure and set the localization culture cookie within the app's scheme.

Im folgenden Beispiel wird veranschaulicht, wie die aktuelle Kultur in einem cookie festgelegt werden kann, das von der Lokalisierungsmiddleware gelesen werden kann.The following example shows how to set the current culture in a cookie that can be read by the Localization Middleware. Erstellen Sie in der Pages/_Host.cshtml-Datei direkt innerhalb des öffnenden <body>-Tags einen Razor-Ausdruck:Create a Razor expression in the Pages/_Host.cshtml file immediately inside the opening <body> tag:

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

...

<body>
    @{
        this.HttpContext.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(
                    CultureInfo.CurrentCulture,
                    CultureInfo.CurrentUICulture)));
    }

    ...
</body>

Die Lokalisierung wird mit der folgenden Ereignissequenz von der App verarbeitet:Localization is handled by the app in the following sequence of events:

  1. Der Browser sendet zunächst eine HTTP-Anforderung an die App.The browser sends an initial HTTP request to the app.
  2. Die Kultur wird von der Lokalisierungsmiddleware zugewiesen.The culture is assigned by the Localization Middleware.
  3. Der Razor-Ausdruck auf der _Host-Seite (_Host.cshtml) speichert die Kultur im Rahmen der Reaktion in einem cookie.The Razor expression in the _Host page (_Host.cshtml) persists the culture in a cookie as part of the response.
  4. Der Browser stellt eine WebSocket-Verbindung her, um eine interaktive Blazor Server-Sitzung zu erstellen.The browser opens a WebSocket connection to create an interactive Blazor Server session.
  5. Die Lokalisierungsmiddleware liest das cookie und weist die Kultur zu.The Localization Middleware reads the cookie and assigns the culture.
  6. Die Blazor Server-Sitzung beginnt mit der richtigen Kultur.The Blazor Server session begins with the correct culture.

Verwenden Sie bei der Arbeit mit einer RazorPage die Context-Eigenschaft:When working with a RazorPage, use the Context property:

@{
    this.Context.Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(
            new RequestCulture(
                CultureInfo.CurrentCulture,
                CultureInfo.CurrentUICulture)));
}

Bereitstellen einer Benutzeroberfläche zum Auswählen der KulturProvide UI to choose the culture

Zum Bereitstellen einer Benutzeroberfläche, um Benutzern das Auswählen einer Kultur zu ermöglichen, wird ein Ansatz auf Grundlage von Umleitungen empfohlen.To provide UI to allow a user to select a culture, a redirect-based approach is recommended. Dieses Verfahren ähnelt dem, was in einer Web-App passiert, wenn ein Benutzer versucht, auf eine sichere Ressource zuzugreifen.The process is similar to what happens in a web app when a user attempts to access a secure resource. Der Benutzer wird auf eine Anmeldeseite umgeleitet und dann zurück zur ursprünglichen Ressource.The user is redirected to a sign-in page and then redirected back to the original resource.

Die App behält die vom Benutzer ausgewählte Kultur mithilfe einer Umleitung an einen Controller bei.The app persists the user's selected culture via a redirect to a controller. Der Controller legt die ausgewählte Kultur des Benutzers mit einem cookie fest und leitet den Benutzer wieder an den ursprünglichen URI weiter.The controller sets the user's selected culture into a cookie and redirects the user back to the original URI.

Erstellen Sie einen HTTP-Endpunkt auf dem Server zum Festlegen der ausgewählten Kultur eines Benutzers in einem cookie, und leiten Sie ihn dann wieder an den ursprünglichen URI weiter:Establish an HTTP endpoint on the server to set the user's selected culture in a cookie and perform the redirect back to the original URI:

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

        return LocalRedirect(redirectUri);
    }
}

Warnung

Verwenden Sie das Ergebnis der LocalRedirect-Aktion, um Angriffe durch offene Umleitungen zu verhindern.Use the LocalRedirect action result to prevent open redirect attacks. Weitere Informationen finden Sie unter Verhindern offener Weiterleitungs Angriffe in ASP.net Core.For more information, see Verhindern offener Weiterleitungs Angriffe in ASP.net Core.

Befolgen Sie die folgenden Schritte, wenn die App nicht für die Verarbeitung von Controlleraktionen konfiguriert ist:If the app isn't configured to process controller actions:

  • Fügen Sie MVC-Dienste zur Dienstsammlung in Startup.ConfigureServices hinzu:Add MVC services to the service collection in Startup.ConfigureServices:

    services.AddControllers();
    
  • Fügen Sie das Controllerendpunktrouting in Startup.Configure hinzu:Add controller endpoint routing in Startup.Configure:

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapBlazorHub();
        endpoints.MapFallbackToPage("/_Host");
    });
    

Im folgenden Beispiel wird das Durchführen einer Umleitung veranschaulicht, wenn der Benutzer eine Kultur auswählt:The following component shows an example of how to perform the initial redirection when the user selects a culture:

@inject NavigationManager NavigationManager

<h3>Select your language</h3>

<select @onchange="OnSelected">
    <option>Select...</option>
    <option value="en-US">English</option>
    <option value="fr-FR">Français</option>
</select>

@code {
    private void OnSelected(ChangeEventArgs e)
    {
        var culture = (string)e.Value;
        var uri = new Uri(NavigationManager.Uri)
            .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
        var query = $"?culture={Uri.EscapeDataString(culture)}&" +
            $"redirectUri={Uri.EscapeDataString(uri)}";

        NavigationManager.NavigateTo("/Culture/SetCulture" + query, forceLoad: true);
    }
}

Zusätzliche RessourcenAdditional resources