Реализация стратегии выбора языка и языка и региональных параметров для каждого запроса в локализованном приложении ASP.NET Core

Хишем Бен Атея, Дэмиен Боуден, Барт Каликсто, Надем Афана, и Рик Андерсон

Одной из задач локализации приложения является реализация стратегии выбора соответствующего языка и региональных параметров для каждого ответа, возвращаемого приложением.

Настройка ПО промежуточного слоя локализации

Текущий язык и региональные параметры в запросе задаются в промежуточном слое локализации. ПО промежуточного слоя локализации включено Program.cs. ПО промежуточного слоя локализации должно настраиваться перед другим ПО промежуточного слоя, которое может проверять язык и региональные параметры запроса (например, app.UseMvcWithDefaultRoute()).

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

UseRequestLocalization инициализирует объект RequestLocalizationOptions. При каждом запросе проверяется список поставщиков RequestCultureProvider в объекте RequestLocalizationOptions и используется первый поставщик, который может успешно определить язык и региональные параметры запроса. Поставщики по умолчанию берутся из класса RequestLocalizationOptions:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

В списке по умолчанию поставщики следуют от наиболее конкретных до наиболее общих. Далее в статье вы узнаете, как изменить заказ и даже добавить настраиваемый поставщик языка и региональных параметров. Если ни один из поставщиков не может определить язык и региональные параметры запроса, используется DefaultRequestCulture.

QueryStringRequestCultureProvider

Для задания CultureInfoнекоторых приложений используется строка запроса. Если в приложении для этого применяется файл cookie или заголовок Accept-Language, добавление строки запроса к URL-адресу может быть полезным в целях отладки и тестирования кода. По умолчанию поставщик QueryStringRequestCultureProvider регистрируется в качестве первого поставщика локализации в списке RequestCultureProvider. Вы передаете параметры строки запроса culture и ui-culture. В следующем примере в качестве языка и региональных параметров (язык и регион) задаются испанский язык и Мексика:

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

Если он передается только culture или ui-culture передается, поставщик строки запроса задает оба значения, используя переданный. Например, если передан только язык и региональные параметры, будут заданы оба значения Culture и UICulture:

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

CookieRequestCultureProvider

Рабочие приложения часто предоставляют механизм для указания языка и региональных параметров с помощью соответствующего файла cookie ASP.NET Core. Чтобы создать файл MakeCookieValue, используйте метод cookie.

CookieRequestCultureProvider DefaultCookieName возвращает имя файла cookie по умолчанию, с помощью которого отслеживается предпочтительный язык и региональные параметры пользователя. Имя cookie по умолчанию — .AspNetCore.Culture.

Файл cookie имеет формат c=%LANGCODE%|uic=%LANGCODE%, где c — это Culture, а uic — это UICulture, например:

c=en-UK|uic=en-US

Если предоставляется только одна из сведений о языке и региональных параметрах или языке пользовательского интерфейса, предоставленные язык и региональные параметры используются как для сведений о языках и региональных параметров, так и для языка и региональных параметров пользовательского интерфейса.

Заголовок HTTP Accept-Language

Заголовок Accept-Language может задаваться в большинстве браузеров и изначально предназначался для указания языка пользователя. Он показывает, какой язык был выбран в браузере или унаследован от базовой операционной системы. Заголовок HTTP Accept-Language в запросе из браузера — это не самый надежный способ определения предпочтительного языка пользователя (см. статью Настройка языковых предпочтений в браузере). В рабочем приложении должна быть возможность выбора языка и региональных параметров пользователем.

Установка заголовка HTTP на языке Accept-Language в Edge

1. Параметры поиска для предпочитаемых языков.

2. Предпочитаемые языки перечислены в поле "Предпочитаемые языки ".

3. Выберите " Добавить языки " для добавления в список.

4. Выберите дополнительные действия ... рядом с языком, чтобы изменить порядок предпочтений.

Заголовок HTTP Content-Language

Заголовок сущности Content-Language:

• Используется для описания языков, предназначенных для аудитории.
• Позволяет пользователю различать в соответствии с предпочтительным языком пользователя.

Заголовки сущностей используются как в HTTP-запросах, так и в ответах.

Заголовок Content-Language можно добавить, задав свойство ApplyCurrentCultureToResponseHeaders.

Добавление заголовка Content-Language:

• RequestLocalizationMiddleware Позволяет задать Content-Language заголовок с помощью CurrentUICulture.
• Устраняет необходимость явной установки заголовка ответа Content-Language.

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

Применение RouteDataRequest CultureProvider

Задает RouteDataRequestCultureProvider язык и региональные параметры на основе значения culture маршрута. Дополнительные сведения см. в разделе "Поставщик языка и региональных параметров URL-адресов", использующий ПО промежуточного слоя в качестве фильтров :

• Использование ПО промежуточного слоя в качестве функции фильтров ASP.NET Core.
• Как задать RouteDataRequestCultureProvider язык и региональные параметры приложения из URL-адреса.

См. статью "Применение RouteDataRequest CultureProvider глобально с помощью по промежуточного слоя" в качестве фильтров для получения сведений о том, как применять глобальное RouteDataRequestCultureProvider значение.

Использование пользовательского поставщика

Предположим, необходимо, чтобы ваши клиенты могли сохранять информацию о своем языке и региональных параметрах в ваших базах данных. Можно написать поставщик, который будет искать эти значения для пользователя. В следующем примере кода показано, как добавить пользовательский поставщик:

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

Для добавления или удаления поставщиков локализации используйте объект RequestLocalizationOptions.

Изменение порядка поставщиков языка и региональных параметров запроса

В RequestLocalizationOptions три поставщика языка и региональных параметров запроса по умолчанию: QueryStringRequestCultureProvider, CookieRequestCultureProvider и AcceptLanguageHeaderRequestCultureProvider. Используйте свойство RequestLocalizationOptions.RequestCultureProviders, чтобы изменить порядок этих поставщиков, как показано ниже:

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

В приведенном выше примере порядок QueryStringRequestCultureProvider и CookieRequestCultureProvider переключение, поэтому RequestLocalizationMiddleware сначала ищет язык и региональные параметры из файлов cookie, а затем строку запроса.

Как уже упоминалось, нужно добавить пользовательский поставщик с помощью метода AddInitialRequestCultureProvider, который назначает приоритет 0, чтобы этот поставщик имел приоритет над другими.

Язык и региональные параметры переопределения пользователей

Свойство RequestLocalizationOptions.CultureInfoUseUserOverride позволяет приложению решить, следует ли использовать параметры Windows, отличные от по умолчанию, для CultureInfo DateTimeFormat свойств и NumberFormat свойств. Это не влияет на Linux. Это напрямую UseUserOverrideсоответствует .

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

Задание языка и региональных параметров программным образом

В образце проекта Localization.StarterWeb в GitHub есть пользовательский интерфейс для задания значения Culture. Файл Views/Shared/_SelectLanguagePartial.cshtml позволяет выбрать язык и региональные параметры из списка поддерживаемых языков и региональных параметров:

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

Файл Views/Shared/_SelectLanguagePartial.cshtml добавляется в раздел footer файла макета, поэтому он доступен всем представлениям:

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

Метод SetLanguage задает файл 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);
}

Вы не можете подключить _SelectLanguagePartial.cshtml пример кода для этого проекта. В проекте Localization.StarterWeb в GitHub есть код для передачи объекта RequestLocalizationOptions в частичное представление Razor посредством контейнера внедрения зависимостей.

Данные маршрутов привязки модели и строки запросов

См. раздел Поведение глобализации для данных маршрутов привязки модели и строк запросов.

Следующие шаги

Локализация приложения также включает следующие задачи:

• Сделайте содержимое приложения локализуемым.
• Предоставление локализованных ресурсов для языков и региональных параметров, поддерживаемых приложением

Дополнительные ресурсы

• Поставщик языка и региональных параметров URL-адреса с помощью по промежуточного слоя в качестве фильтров в ASP.NET Core
• Применение RouteDataRequest CultureProvider глобально с по промежуточного слоя в качестве фильтров
• Глобализация и локализация в ASP.NET Core
• Сделать содержимое приложения ASP.NET Core локализуемым
• Предоставление локализованных ресурсов для языков и региональных параметров в приложении ASP.NET Core
• Устранение неполадок локализации ASP.NET Core
• Глобализация и локализация приложений .NET
• Проект Localization.StarterWeb, используемый в этой статье.
• Ресурсы в RESX-файлах
• Набор средств многоязычных приложений Майкрософт
• Локализация и универсальные шаблоны