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

Примечание.

Это не последняя версия этой статьи. В текущей версии см. версию .NET 10 этой статьи.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущей версии см. версию .NET 10 этой статьи.

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

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

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

Текущая культура в запросе задается в Middleware локализации. Локализационное промежуточное ПО включено 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:

В списке по умолчанию элементы располагаются от наиболее конкретных к наименее конкретным. Далее в статье вы узнаете, как изменить порядок и даже добавить настраиваемого поставщика языковых и региональных параметров. Если ни один из поставщиков не может определить культуру запроса, используется 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

Рабочие приложения часто предоставляют механизм для установки культурных параметров с помощью ASP.NET Core cookie. Используйте метод 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

Параметры поиска для предпочитаемых языков.
Предпочитаемые языки перечислены в поле "Предпочитаемые языки ".
Выберите " Добавить языки " для добавления в список.
Выберите дополнительные действия ... рядом с языком, чтобы изменить порядок предпочтений.

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

Заголовок сущности 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 глобально с помощью промежуточного слоя (middleware)" для получения информации о том, как применять это глобально с помощью 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 посредством контейнера внедрения зависимостей.

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

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

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

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

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

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

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

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

QueryStringRequestCultureProvider

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

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

CookieRequestCultureProvider

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

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

c=en-UK|uic=en-US

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

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

Установить HTTP-заголовок Accept-Language в Edge

Параметры поиска для предпочитаемых языков.
Предпочитаемые языки перечислены в поле "Предпочитаемые языки ".
Выберите " Добавить языки " для добавления в список.
Выберите дополнительные действия ... рядом с языком, чтобы изменить порядок предпочтений.

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

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

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

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

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

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

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

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

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

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.

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

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

Установите культуру программно

В образце проекта 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>

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

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

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

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

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

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

Авторы: Рик Андерсон (Rick Anderson), Дэмиен Боуден (Damien Bowden), Барт Каликсто (Bart Calixto), Надим Афана (Nadeem Afana) и Хишам Бин Атея (Hisham Bin Ateya)

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

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

var supportedCultures = new[] { "en-US", "fr" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

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

QueryStringRequestCultureProvider
CookieRequestCultureProvider
AcceptLanguageHeaderRequestCultureProvider

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

Рабочие приложения часто предоставляют механизм для установки культурных параметров с помощью ASP.NET Core cookie. Используйте метод 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

Установить HTTP-заголовок Accept-Language в Edge

Параметры поиска для предпочитаемых языков.
Предпочитаемые языки перечислены в поле "Предпочитаемые языки ".
Выберите " Добавить языки " для добавления в список.
Выберите дополнительные действия ... рядом с языком, чтобы изменить порядок предпочтений.

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

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

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

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

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

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

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

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

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

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.

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

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

Установить язык и региональные параметры программно

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

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

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

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

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

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

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-11