RequestLocalizationMiddleware

Данное руководство устарело. Актуальное руководство: Руководство по ASP.NET Core 7

В прошлой теме было рассмотрено получение и установка культуры с помощью самописного функционала. Однако ASP.NET Core уже по умолчанию предоставляет специальный компонент middleware, который упрощает нам локализацию - RequestLocalizationMiddleware. Пр каждом запросе этот компонент автоматически устанавливает значения культуры на основе пришедших в запросе данных.

Для применения RequestLocalizationMiddleware используется специальный метод расширения app.UseRequestLocalization. Используем его, изменив файл Startup.cs:

using System.Globalization;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Localization;
using Microsoft.Extensions.DependencyInjection;

namespace LocalizationApp
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllersWithViews();
        }

        public void Configure(IApplicationBuilder app)
        {
            app.UseDeveloperExceptionPage();

            var supportedCultures = new[]
            {
                new CultureInfo("en-US"),
                new CultureInfo("en-GB"),
                new CultureInfo("en"),
                new CultureInfo("ru-RU"),
                new CultureInfo("ru"),
                new CultureInfo("de-DE"),
                new CultureInfo("de")
            };
            app.UseRequestLocalization(new RequestLocalizationOptions
            {
                DefaultRequestCulture = new RequestCulture("ru-RU"),
                SupportedCultures = supportedCultures,
                SupportedUICultures = supportedCultures
            });

            app.UseStaticFiles();

            app.UseRouting();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllerRoute(
                    name: "default",
                    pattern: "{controller=Home}/{action=Index}/{id?}");
            });
        }
    }
}

Метод UseRequestLocalization() инициализирует объект RequestLocalizationOptions с помощью ряда значений. В частности, у RequestLocalizationOptions устанавливается текущая культура с помощью свойства DefaultRequestCulture, а также список поддерживаемых культур посредством свойств SupportedCultures и SupportedUICultures.

При каждом запросе в объекте RequestLocalizationOptions перебирается список провайдеров. Первый попавшийся провайдер, который определит культуру, будет использоваться для обработки запроса.

По умолчанию в RequestLocalizationOptions определено несколько провайдеров, каждый из которых связан с определенным источником данных:

• QueryStringRequestCultureProvider

• CookieRequestCultureProvider

• AcceptLanguageHeaderRequestCultureProvider

QueryStringRequestCultureProvider

QueryStringRequestCultureProvider устанавливает текущую культуру на основании строки запроса. При этом в запросе должны присутствовать параметры culture и ui-culture. Например, запрос может выглядеть следующим образом:

http://localhost:5000/?culture=en-US&ui-culture=en-US

В данном случае будет использоваться культура "en-US".

Если один из этих двух параметров опущен, то другой применяется сразу для CurrentCulture и CurrentUICulture.

CookieRequestCultureProvider

CookieRequestCultureProvider извлекает код культуры из куки. По умолчанию такая куки имеет имя ".AspNetCore.Culture", а сам формат хранимого в ней значения выглядит следующим образом:

c=%LANGCODE%|uic=%LANGCODE%

Здесь c передает CurrentCulture, а uic - CurrentUICulture. Например: c=de-DE|uic=de-DE.

Также кука может хранить только одно значение, тогда оно будет распространяться на оба параметра.

AcceptLanguageHeaderRequestCultureProvider

AcceptLanguageHeaderRequestCultureProvider извлекает код культуры из заголовка Accept-Language, который передается в запросе. Обратите внимание, что браузеры могут автоматически настраивать этот заголовок. И даже если вы установите в определенную культуру по умолчанию (как в случае выше это "ru-RU"), значение этого заголовка ее сбрасывает. Например, на руссифцированной операционной системе установлен англоязычный браузер, который посылает заголовок "accept-language: en-US,en;q=0.9". В итоге и культура будет "en-US".

Приоритет провайдеров

Наиболее приоритетным является QueryStringRequestCultureProvider. Если в строке запроса не найдено определение культуры, тогда используется провайдер CookieRequestCultureProvider, который использует куки. Если в куках не найдено определение культуры, тогда применяется AcceptLanguageHeaderRequestCultureProvider, который использует заголовок Accept-Language.

Например, возьмем метод контроллера, который выводит культуру:

public string GetCulture()
{
	return $"CurrentCulture:{CultureInfo.CurrentCulture.Name}, CurrentUICulture:{CultureInfo.CurrentUICulture.Name}";
}

И передадим приложению через строку запроса языковой код:

Стоит отметить, что не все переданные значения будут использоваться для установки культуры, а только те, которые определены в свойствах SupportedCultures и SupportedUICultures при настройке в классе Startup. Если будет передана не поддерживаемая культура, то вместо нее будет применяться культура по умолчанию.