Implementace strategie pro výběr jazyka a jazykové verze pro každý požadavek v lokalizované aplikaci ASP.NET Core

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

Jednou z úloh pro lokalizaci aplikace je implementace strategie pro výběr vhodné jazykové verze pro každou odpověď, která aplikace vrátí.

Konfigurace middlewaru lokalizace

Aktuální jazyková verze požadavku je nastavená v middlewaru lokalizace. Lokalizační middleware je povolený v Program.cssouboru . Middleware lokalizace musí být nakonfigurovaný před jakýmkoli middlewarem, který může zkontrolovat jazykovou verzi požadavku (například app.UseMvcWithDefaultRoute()).

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

UseRequestLocalization inicializuje RequestLocalizationOptions objekt. Na každém požadavku je seznam výčtu RequestCultureProvider RequestLocalizationOptions a první zprostředkovatel, který může úspěšně určit jazykovou verzi požadavku. Výchozí zprostředkovatelé pocházejí z RequestLocalizationOptions třídy:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

Výchozí seznam pochází od nejvýraznějšího po nejpodobnější. Později v článku se dozvíte, jak můžete změnit pořadí a dokonce přidat vlastního zprostředkovatele jazykové verze. Pokud žádný z poskytovatelů nemůže určit jazykovou verzi požadavku, použije se DefaultRequestCulture .

QueryStringRequestCultureProvider

Některé aplikace budou k nastavení CultureInfořetězce dotazu používat řetězec dotazu . Pro aplikace, které používají přístup hlavičky cookie Nebo Accept-Language, je přidání řetězce dotazu na adresu URL užitečné pro ladění a testování kódu. Ve výchozím nastavení je zaregistrovaný QueryStringRequestCultureProvider jako první zprostředkovatel lokalizace v RequestCultureProvider seznamu. Předáte parametry culture řetězce dotazu a ui-culture. Následující příklad nastaví konkrétní jazykovou verzi (jazyk a oblast) na španělštinu nebo Mexiko:

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

Pokud je pouze culture nebo ui-culture je předán, poskytovatel řetězce dotazu nastaví obě hodnoty pomocí předaného. Například nastavení pouze jazykové verze nastaví Culture obě verze a UICulture:

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

CookieRequestCultureProvider

Produkční aplikace často poskytují mechanismus nastavení jazykové verze s jazykovou verzí ASP.NET Core cookie. Použijte metodu MakeCookieValue cookiek vytvoření .

Vrátí CookieRequestCultureProvider DefaultCookieName výchozí cookie název použitý ke sledování upřednostňovaných informací o jazykové verzi uživatele. Výchozí cookie název je .AspNetCore.Culture.

Formát cookie je c=%LANGCODE%|uic=%LANGCODE%, kde c je Culture a uic je UICulture, například:

c=en-UK|uic=en-US

Pokud je k dispozici pouze jedna z informací o jazykové verzi nebo jazykové verze uživatelského rozhraní, použije se poskytnutá jazyková verze pro informace o jazykové verzi i jazykovou verzi uživatelského rozhraní.

Hlavička HTTP jazyka Accept

Hlavička Accept-Language je ve většině prohlížečů nastavená a původně byla určena k určení jazyka uživatele. Toto nastavení označuje, co byl prohlížeč nastavený tak, aby odesílal nebo zdědil ze základního operačního systému. Hlavička HTTP jazyka Accept-Language z požadavku prohlížeče není nechtěným způsobem, jak rozpoznat upřednostňovaný jazyk uživatele (viz Nastavení jazykových předvoleb v prohlížeči). Produkční aplikace by měla obsahovat způsob, jak si uživatel přizpůsobit svou volbu jazykové verze.

Nastavení hlavičky HTTP pro accept-language v Edgi

1. Nastavení vyhledávání pro upřednostňované jazyky

2. Upřednostňované jazyky jsou uvedeny v poli Upřednostňované jazyky .

3. Vyberte Přidat jazyky , které chcete přidat do seznamu.

4. Vyberte Další akce ... vedle jazyka a změňte pořadí předvoleb.

Hlavička HTTP jazyka Content-Language

Hlavička entity Content-Language :

• Slouží k popisu jazyků určených pro cílovou skupinu.
• Umožňuje uživateli rozlišovat podle vlastního upřednostňovaného jazyka uživatele.

Hlavičky entit se používají v požadavcích HTTP i odpovědích.

Záhlaví Content-Language lze přidat nastavením vlastnosti ApplyCurrentCultureToResponseHeaders.

Content-Language Přidání záhlaví:

• RequestLocalizationMiddleware Umožňuje nastavit Content-Language záhlaví pomocí CurrentUICulture.
• Eliminuje potřebu explicitně nastavit hlavičku Content-Language odpovědi.

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

Použití RouteDataRequest CultureProvider

Jazyková RouteDataRequestCultureProvider verze se nastaví na základě hodnoty culture hodnoty trasy. Informace o poskytovateli jazykové verze adresy URL, který používá middleware jako filtry :

• Použití middlewaru jako funkce filtrů ASP.NET Core
• Jak nastavit RouteDataRequestCultureProvider jazykovou verzi aplikace z adresy URL.

Viz Použití RouteDataRequest CultureProvider globálně s middlewarem jako filtry , kde najdete informace o tom, jak globálně použít RouteDataRequestCultureProvider .

Použití vlastního zprostředkovatele

Předpokládejme, že chcete zákazníkům umožnit ukládat jejich jazyk a kulturu do databází. Můžete napsat zprostředkovatele, který vyhledá tyto hodnoty pro uživatele. Následující kód ukazuje, jak přidat vlastního zprostředkovatele:

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

Slouží RequestLocalizationOptions k přidání nebo odebrání zprostředkovatelů lokalizace.

Změna pořadí poskytovatelů jazykové verze žádosti

RequestLocalizationOptions má tři výchozí poskytovatele jazykové verze žádostí: QueryStringRequestCultureProvider, CookieRequestCultureProvidera AcceptLanguageHeaderRequestCultureProvider. Pomocí RequestLocalizationOptions.RequestCultureProviders vlastnosti můžete změnit pořadí těchto poskytovatelů, jak je znázorněno níže:

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

V předchozím příkladu se pořadí QueryStringRequestCultureProvider a CookieRequestCultureProvider přepnutí, takže RequestLocalizationMiddleware hledá jazykové verze z cookieprvního řetězce dotazu.

Jak jsme už zmínili, přidejte vlastního zprostředkovatele, který AddInitialRequestCultureProvider nastaví pořadí na 0, takže tento zprostředkovatel má přednost před ostatními.

Jazyková verze přepsání uživatelem

Vlastnost RequestLocalizationOptions.CultureInfoUseUserOverride umožňuje aplikaci rozhodnout, jestli pro vlastnosti a NumberFormat vlastnosti použít jiné než výchozí nastavení CultureInfo DateTimeFormat Windows. To nemá žádný vliv na Linux. To přímo odpovídá UseUserOverride.

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

Nastavení jazykové verze prostřednictvím kódu programu

Tento ukázkový projekt Localization.StarterWeb na GitHubu Cultureobsahuje uživatelské rozhraní pro nastavení . Soubor Views/Shared/_SelectLanguagePartial.cshtml umožňuje vybrat jazykovou verzi ze seznamu podporovaných jazykových verzí:

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

Soubor Views/Shared/_SelectLanguagePartial.cshtml se přidá do footer části souboru rozložení, takže bude k dispozici pro všechna zobrazení:

<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 nastaví jazykovou verzi 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);
}

Ukázkový kód pro tento projekt se nedá připojit _SelectLanguagePartial.cshtml . Projekt Localization.StarterWeb na GitHubu má kód pro tok do RequestLocalizationOptions Razor částečné části prostřednictvím kontejneru injektáže závislostí.

Vazba modelu směruje data a řetězce dotazů

Viz Chování globalizace vazby modelu směrovat data a řetězce dotazů.

Další kroky

Lokalizace aplikace zahrnuje také následující úlohy:

• Nastavení lokalizovatelného obsahu aplikace
• Poskytnutí lokalizovaných prostředků pro jazyky a jazykové verze, které aplikace podporuje

Další materiály

• Poskytovatel jazykové verze adresy URL, který používá middleware jako filtry v ASP.NET Core
• Globální použití RouteDataRequest CultureProvideru s middlewarem jako filtry
• Globalizace a lokalizace v ASP.NET Core
• Nastavení lokalizovatelného obsahu aplikace ASP.NET Core
• Poskytnutí lokalizovaných prostředků pro jazyky a jazykové verze v aplikaci ASP.NET Core
• Řešení potíží s lokalizací ASP.NET Core
• Globalizace a lokalizace aplikací .NET
• Projekt Localization.StarterWeb použitý v článku
• Prostředky v souborech .resx
• Microsoft Multilingual App Toolkit
• Lokalizace a obecné typy