Implementieren einer Strategie zum Auswählen der Sprache/Kultur für jede Anforderung in einer lokalisierten ASP.NET Core-App

Hisham Bin Ateya, Damien Bowden, Bart Calixto, Nadeem Afana und Rick Anderson

Eine Aufgabe zum Lokalisieren einer App besteht darin, eine Strategie zum Auswählen der geeigneten Kultur für jede Antwort zu implementieren, die die App zurückgibt.

Konfigurieren der Lokalisierungsmiddleware

Die aktuell angefragte Kultur wird in der Middleware für die Lokalisierung festgelegt. Die Middleware für die Lokalisierung wird in Program.cs aktiviert. Die Lokalisierungsmiddleware muss vor Middleware konfiguriert werden, die möglicherweise die Anforderungskultur prüft (z. B. app.UseMvcWithDefaultRoute()).

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[] { "en-US", "fr" };
    options.SetDefaultCulture(supportedCultures[0])
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);
});

UseRequestLocalization initialisiert ein RequestLocalizationOptions-Objekt. Bei jeder Anforderung wird die Liste von RequestCultureProvider in RequestLocalizationOptions aufgelistet und der erste Anbieter, der erfolgreich die Anforderungskultur bestimmen kann, wird verwendet. Die Standardanbieter stammen aus der Klasse RequestLocalizationOptions:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

Die Reihenfolge der Standardliste fängt bei den spezifischsten Anbietern an und endet mit den allgemeinsten. Im Verlauf des Artikels erfahren Sie, wie Sie die Reihenfolge ändern und einen benutzerdefinierten Kulturanbieter hinzufügen. Wenn kein Anbieter die Anforderungskultur bestimmen kann, wird DefaultRequestCulture verwendet.

QueryStringRequestCultureProvider

Einige Apps verwenden eine Abfragezeichenfolge, um die CultureInfo festzulegen. Bei Apps, die die Ansätze cookie oder Accept-Language-Header verwenden, ist das Hinzufügen einer Abfragezeichenfolge zur URL für das Debuggen und Testen von Code nützlich. Standardmäßig ist QueryStringRequestCultureProvider als erster Lokalisierungsanbieter in der Liste RequestCultureProvider registriert. Sie übergeben die Abfragezeichenfolge-Parameter culture und ui-culture. Im folgenden Beispiel ist die spezifische Kultur (Sprache und Region) auf Spanisch/Mexiko festgelegt:

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

Wenn nur culture oder nur ui-culture übergeben wird, legt der Anbieter der Abfragezeichenfolge beide Werte auf den übergebenen Wert fest. Wenn beispielsweise nur die Kultur festgelegt wird, werden sowohl Culture als auch UICulture wie folgt festgelegt:

http://localhost:5000/?culture=es-MX

CookieRequestCultureProvider

Produktions-Apps bieten oft einen Mechanismus zum Festlegen der Kultur mithilfe des ASP.NET Core-Kulturcookies. Verwenden Sie die Methode MakeCookieValue zum Erstellen eines cookies.

CookieRequestCultureProviderDefaultCookieName gibt den standardmäßigen cookie-Namen zurück, mit dem ermittelt wird, welche Kulturinformationen der Benutzer bevorzugt. Der Standardcookiename lautet .AspNetCore.Culture.

Das cookieformat ist c=%LANGCODE%|uic=%LANGCODE%, wobei c für Culture steht und uic für UICulture, zum Beispiel:

c=en-UK|uic=en-US

Wenn nur die Kulturinformation oder nur die Benutzeroberflächenkultur verfügbar ist, wird die bereitgestellte Kultur sowohl für die Kulturinformation als auch für die Benutzeroberflächenkultur verwendet.

Der Accept-Language-HTTP-Header

Der Accept-Language-Header ist in den meisten Browsern konfigurierbar und war ursprünglich dafür gedacht, die Sprache des Benutzers anzugeben. Diese Einstellung gibt an, was im Browser zum Senden festgelegt ist oder vom zugrunde liegenden Betriebssystem geerbt wurde. Der Accept-Language-HTTP-Header einer Browseranfrage ist keine unfehlbare Methode zum Erkennen der bevorzugten Sprache des Benutzers (siehe Setting language preferences in a browser (Festlegen der bevorzugten Sprache in einem Browser)). In einer Produktions-App sollten Benutzer die Möglichkeit haben, ihre bevorzugte Kultur anzupassen.

Festlegen des Accept-Language-HTTP-Headers in Edge

1. Sucheinstellungen für bevorzugte Sprachen.

2. Die bevorzugten Sprachen sind im Feld Bevorzugte Sprachen aufgeführt.

3. Wählen Sie Sprachen hinzufügen aus, um sie der Liste hinzuzufügen.

4. Wählen Sie Weitere Aktionen ... neben einer Sprache aus, um die bevorzugte Reihenfolge zu ändern.

Der Content-Language-HTTP-Header

Der Content-Language-Entitätsheader:

• Wird verwendet, um die für die Zielgruppe vorgesehenen Sprachen zu beschreiben.
• Ermöglicht einem Benutzer, gemäß seiner bevorzugten Sprache zu differenzieren.

Entitätsheader werden in HTTP-Anforderungen und -Antworten verwendet.

Der Content-Language-Header kann durch Festlegen der Eigenschaft ApplyCurrentCultureToResponseHeaders hinzugefügt werden.

Hinzufügen des Content-Language-Headers:

• Ermöglicht RequestLocalizationMiddleware das Festlegen des Content-Language-Headers mit CurrentUICulture.
• Macht das explizite Festlegen des Content-Language-Antwortheaders überflüssig.

app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

Anwenden des RouteDataRequest CultureProviders

Die RouteDataRequestCultureProvider Kultur wird basierend auf dem Wert des culture Routenwerts festgelegt. Informationen finden Sie unter URL-Kulturanbieter, der Middleware als Filter verwendet:

• Verwenden der Middleware als Filterfeature von ASP.NET Core.
• So verwenden Sie RouteDataRequestCultureProvider, um die Kultur einer App über die URL festzulegen.

Informationen zur globalen Anwendung des RouteDataRequest CultureProvider mit Middleware finden Sie unter „Anwenden des RouteDataRequest CultureProvider“ als FilterRouteDataRequestCultureProvider.

Verwenden eines benutzerdefinierten Anbieters

Angenommen, Sie möchten Ihren Kunden das Speichern ihrer Sprache und Kultur in Ihren Datenbanken ermöglichen. In diesem Fall können Sie einen Anbieter codieren, der diese Werte für den Benutzer abruft. Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen benutzerdefinierten Anbieter hinzufügen:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return await Task.FromResult(new ProviderCultureResult("en"));
    }));
});

Verwenden Sie RequestLocalizationOptions, um Lokalisierungsanbieter hinzuzufügen oder zu entfernen.

Ändern der Reihenfolge der Anforderungskulturanbieter

RequestLocalizationOptions hat drei Standardanbieter für Anforderungen der Kultur: QueryStringRequestCultureProvider, CookieRequestCultureProvider und AcceptLanguageHeaderRequestCultureProvider. Verwenden Sie die Eigenschaft RequestLocalizationOptions.RequestCultureProviders, um die Reihenfolge dieser Anbieter wie unten gezeigt zu ändern:

    app.UseRequestLocalization(options =>
    {
        var questStringCultureProvider = options.RequestCultureProviders[0];    
        options.RequestCultureProviders.RemoveAt(0);
        options.RequestCultureProviders.Insert(1, questStringCultureProvider);
    });

Im vorstehenden Beispiel ist die Reihenfolge von QueryStringRequestCultureProvider und CookieRequestCultureProvider umgestellt, sodass RequestLocalizationMiddleware zuerst in den cookies und dann in der Abfragezeichenfolge nach den Kulturen sucht.

Wie bereits erwähnt, fügen Sie über AddInitialRequestCultureProvider einen benutzerdefinierten Anbieter hinzu, der die Reihenfolge auf 0 festlegt, sodass dieser Anbieter Vorrang vor den anderen hat.

Überschreiben der Kultur durch Benutzer*innen

Mit der Eigenschaft RequestLocalizationOptions.CultureInfoUseUserOverride kann die App festlegen, ob nicht standardmäßige Windows-Einstellungen für die Eigenschaften CultureInfoDateTimeFormat und NumberFormat verwendet werden sollen oder nicht. Dies hat in Linux keine Auswirkungen. Dies ist eine direkte Entsprechung von UseUserOverride.

    app.UseRequestLocalization(options =>
    {
        options.CultureInfoUseUserOverride = false;
    });

Programmgesteuertes Festlegen der Kultur

Das Beispielprojekt Localization.StarterWeb auf GitHub enthält eine Benutzeroberfläche zum Festlegen von Culture. Die Datei Views/Shared/_SelectLanguagePartial.cshtml ermöglicht Ihnen das Auswählen der Kultur aus der Liste von unterstützten Kulturen:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Die Datei Views/Shared/_SelectLanguagePartial.cshtml wird dem Abschnitt footer der Layoutdatei hinzugefügt, damit sie für alle Ansichten verfügbar ist:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

Die Methode SetLanguage legt das Kulturcookie fest.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
    );

    return LocalRedirect(returnUrl);
}

Sie können _SelectLanguagePartial.cshtml dem Beispielcode für dieses Projekt nicht hinzufügen. Das Projekt Localization.StarterWeb auf GitHub enthält Code, der RequestLocalizationOptions durch den Container von Dependency Injection an eineRazor-Teilansicht übermittelt.

Routendaten und Abfragezeichenfolgen für die Modellbindung

Weitere Informationen finden Sie unter Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die Modellbindung.

Nächste Schritte

Das Lokalisieren einer App umfasst zudem die folgenden Aufgaben:

• Den Inhalt der App lokalisierbar machen.
• Bereitstellen der lokalisierten Ressourcen für die von der App unterstützten Sprachen und Kulturen

Zusätzliche Ressourcen

• URL-Kulturanbieter, der Middleware als Filter in ASP.NET Core verwendet
• Globales Anwenden von RouteDataRequest CultureProvider mit Middleware als Filter
• Globalisierung und Lokalisierung in ASP.NET Core
• Den Inhalt einer ASP.NET Core-App lokalisierbar machen
• Bereitstellen lokalisierter Ressourcen für Sprachen und Kulturen in einer ASP.NET Core-App
• Problembehandlung bei der ASP.NET Core-Lokalisierung
• Globalisieren und Lokalisieren von .NET-Anwendungen
• Localization.StarterWeb-Projekt wird im Artikel verwendet.
• Ressourcen in RESX-Dateien
• Microsoft Multilingual App Toolkit
• Lokalisierung und Generics