Implementowanie strategii wybierania języka/kultury dla każdego żądania w zlokalizowanej aplikacji ASP.NET Core

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

Jednym z zadań lokalizowania aplikacji jest zaimplementowanie strategii wybierania odpowiedniej kultury dla każdej odpowiedzi zwracanej przez aplikację.

Konfigurowanie oprogramowania pośredniczącego lokalizacji

Bieżąca kultura żądania jest ustawiona w oprogramowania pośredniczącego lokalizacji. Oprogramowanie pośredniczące lokalizacji jest włączone w programie Program.cs. Oprogramowanie pośredniczące lokalizacji musi być skonfigurowane przed każdym oprogramowaniem pośredniczącym, które może sprawdzać kulturę żądania (na przykład app.UseMvcWithDefaultRoute()).

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

UseRequestLocalization inicjuje RequestLocalizationOptions obiekt. Na każdym żądaniu lista RequestCultureProvider w obiekcie RequestLocalizationOptions jest wyliczana, a pierwszy dostawca, który może pomyślnie określić kulturę żądania, jest używana. Domyślni RequestLocalizationOptions dostawcy pochodzą z klasy:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

Lista domyślna przechodzi od najbardziej specyficznych do najmniej określonych. W dalszej części artykułu zobaczysz, jak można zmienić kolejność, a nawet dodać niestandardowego dostawcę kultury. Jeśli żaden z dostawców nie może określić kultury żądania, DefaultRequestCulture zostanie użyty.

QueryStringRequestCultureProvider

Niektóre aplikacje będą używać ciągu zapytania, aby ustawić CultureInfowartość . W przypadku aplikacji korzystających z metody nagłówka cookie lub Accept-Language dodanie ciągu zapytania do adresu URL jest przydatne do debugowania i testowania kodu. Domyślnie element QueryStringRequestCultureProvider jest zarejestrowany jako pierwszy dostawca lokalizacji na RequestCultureProvider liście. Należy przekazać parametry culture ciągu zapytania i ui-culture. W poniższym przykładzie ustawiono konkretną kulturę (język i region) na hiszpański/Meksyk:

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

Jeśli tylko culture lub ui-culture jest przekazywany, dostawca ciągu zapytania ustawia obie wartości przy użyciu przekazanego elementu . Na przykład ustawienie tylko kultury spowoduje ustawienie zarówno wartości , jak Culture i UICulture:

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

CookieRequestCultureProvider

Aplikacje produkcyjne często udostępniają mechanizm ustawiania kultury przy użyciu kultury cookieASP.NET Core. Użyj metody , MakeCookieValue aby utworzyć element cookie.

Zwraca CookieRequestCultureProvider DefaultCookieName domyślną cookie nazwę używaną do śledzenia preferowanych informacji o kulturze użytkownika. Domyślna cookie nazwa to .AspNetCore.Culture.

Format cookie to c=%LANGCODE%|uic=%LANGCODE%, gdzie c to Culture i uic ma UICulturewartość , na przykład:

c=en-UK|uic=en-US

Jeśli jest dostarczana tylko jedna z informacji o kulturze lub kultury interfejsu użytkownika, podana kultura jest używana zarówno dla informacji o kulturze, jak i kultury interfejsu użytkownika.

Nagłówek HTTP accept-language

Nagłówek Accept-Language jest ustawiany w większości przeglądarek i pierwotnie miał na celu określenie języka użytkownika. To ustawienie wskazuje, które ustawienia przeglądarki zostały ustawione do wysyłania lub dziedziczone z bazowego systemu operacyjnego. Nagłówek HTTP accept-language z żądania przeglądarki nie jest nieomylnym sposobem wykrywania preferowanego języka użytkownika (zobacz Ustawianie preferencji języka w przeglądarce). Aplikacja produkcyjna powinna zawierać sposób dostosowywania wybranej kultury przez użytkownika.

Ustawianie nagłówka HTTP accept-language w przeglądarce Edge

1. Ustawienia wyszukiwania dla preferowanych języków.

2. Preferowane języki są wymienione w polu Preferowane języki .

3. Wybierz pozycję Dodaj języki , aby dodać je do listy.

4. Wybierz pozycję Więcej akcji ... obok języka, aby zmienić kolejność preferencji.

Nagłówek HTTP języka zawartości

Nagłówek jednostki Content-Language :

• Służy do opisywania języków przeznaczonych dla odbiorców.
• Umożliwia użytkownikowi rozróżnienie według preferowanego języka użytkowników.

Nagłówki jednostek są używane zarówno w żądaniach HTTP, jak i w odpowiedziach.

Nagłówek Content-Language można dodać, ustawiając właściwość ApplyCurrentCultureToResponseHeaders.

Dodawanie nagłówka Content-Language :

• RequestLocalizationMiddleware Umożliwia ustawienie nagłówka Content-Language za pomocą polecenia CurrentUICulture.
• Eliminuje konieczność jawnego ustawienia nagłówka Content-Language odpowiedzi.

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

Stosowanie elementu RouteDataRequest CultureProvider

Ustawia RouteDataRequestCultureProvider kulturę na podstawie wartości culture trasy. Aby uzyskać informacje, zobacz Dostawca kultury adresu URL używający oprogramowania pośredniczącego jako filtry:

• Używanie oprogramowania pośredniczącego jako funkcji filtrów ASP.NET Core.
• Jak ustawić RouteDataRequestCultureProvider kulturę aplikacji na podstawie adresu URL.

Aby uzyskać informacje na temat sposobu stosowania globalnego elementu RouteDataRequest CultureProvider z oprogramowaniem pośredniczącym, zobacz Artykuł Applying the RouteDataRequest CultureProvider globalnie with middleware as filters (Stosowanie elementu CultureProvider routeDataRequest globalnie z oprogramowaniem pośredniczącym jako filtry), aby uzyskać informacje na temat sposobu stosowania go RouteDataRequestCultureProvider globalnie.

Używanie dostawcy niestandardowego

Załóżmy, że chcesz umożliwić klientom przechowywanie ich języka i kultury w bazach danych. Możesz napisać dostawcę, aby wyszukać te wartości dla użytkownika. Poniższy kod pokazuje, jak dodać dostawcę niestandardowego:

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"));
    }));
});

Służy RequestLocalizationOptions do dodawania lub usuwania dostawców lokalizacji.

Zmiana kolejności dostawców kultury żądań

RequestLocalizationOptions Ma trzech domyślnych dostawców kultury żądań: QueryStringRequestCultureProvider, CookieRequestCultureProvideri AcceptLanguageHeaderRequestCultureProvider. Użyj RequestLocalizationOptions.RequestCultureProviders właściwości , aby zmienić kolejność tych dostawców, jak pokazano poniżej:

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

W poprzednim przykładzie kolejność QueryStringRequestCultureProvider i CookieRequestCultureProvider jest przełączana, więc RequestLocalizationMiddleware najpierw wyszukuje kultury z plików cookie, a następnie ciąg zapytania.

Jak wspomniano wcześniej, dodaj dostawcę niestandardowego, za pomocą AddInitialRequestCultureProvider którego ustawiono kolejność na 0, więc ten dostawca ma pierwszeństwo przed innymi.

Przesłoń kulturę użytkownika

Właściwość RequestLocalizationOptions.CultureInfoUseUserOverride umożliwia aplikacji podjęcie decyzji, czy dla właściwości i NumberFormat mają być używane ustawienia CultureInfo DateTimeFormat systemu Windows inne niż domyślne. Nie ma to wpływu na system Linux. Odpowiada to bezpośrednio .UseUserOverride

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

Programowe ustawianie kultury

Ten przykładowy projekt Localization.StarterWeb w witrynie GitHub zawiera interfejs użytkownika do ustawienia elementu Culture. Plik Views/Shared/_SelectLanguagePartial.cshtml umożliwia wybranie kultury z listy obsługiwanych kultur:

@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>

Plik Views/Shared/_SelectLanguagePartial.cshtml zostanie dodany do footer sekcji pliku układu, aby był dostępny dla wszystkich widoków:

<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>

Metoda SetLanguage ustawia kulturę cookie.

[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);
}

Nie można podłączyć kodu do przykładowego _SelectLanguagePartial.cshtml kodu dla tego projektu. Projekt Localization.StarterWeb w witrynie GitHub zawiera kod umożliwiający przepływ RequestLocalizationOptions do częściowego Razor kontenera wstrzykiwania zależności.

Modelowanie powiązania danych trasy i ciągów zapytań

Zobacz Zachowanie globalizacji danych trasy powiązania modelu i ciągów zapytań.

Następne kroki

Lokalizowanie aplikacji obejmuje również następujące zadania:

• Umożliwia zlokalizowanie zawartości aplikacji.
• Udostępnianie zlokalizowanych zasobów dla języków i kultur obsługiwanych przez aplikację

Dodatkowe zasoby

• Dostawca kultury adresu URL korzystający z oprogramowania pośredniczącego jako filtry w programie ASP.NET Core
• Globalne stosowanie elementu RouteDataRequest CultureProvider z oprogramowaniem pośredniczącym jako filtrami
• Globalizacja i lokalizacja w ASP.NET Core
• Lokalizacja zawartości aplikacji ASP.NET Core
• Udostępnianie zlokalizowanych zasobów dla języków i kultur w aplikacji ASP.NET Core
• Rozwiązywanie problemów z lokalizacją ASP.NET Core
• Globalizowanie i lokalizowanie aplikacji platformy .NET
• Localization.StarterWeb projektu użytego w artykule.
• Zasoby w plikach resx
• Microsoft Multilingual App Toolkit
• Lokalizacja i typy ogólne