实施策略以在本地化 ASP.NET Core 应用中为每个请求选择语言/区域性

Hisham Bin Ateya、Damien Bowden、Bart Calixto、Nadeem Afana 和 Rick Anderson

本地化应用的一项任务是实施策略，为应用返回的每个响应选择适当的区域性。

配置本地化中间件

在本地化中间件中设置有关请求的当前区域性。 在 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 对象。 在每个请求上，枚举了 RequestLocalizationOptions 的 RequestCultureProvider 列表，使用了可成功决定请求区域性的第一个提供程序。 默认提供程序来自 RequestLocalizationOptions 类：

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

默认列表从最具体到最不具体排序。 在本文的后面部分，你将了解如何更改顺序，甚至添加一个自定义区域性提供程序。 如果没有一个提供程序可以确定请求区域性，则使用 DefaultRequestCulture。

QueryStringRequestCultureProvider

某些应用将使用查询字符串来设置CultureInfo。 对于使用 cookie 或接受语言标题方法的应用，向 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 设置区域性。 若要创建 cookie，请使用 MakeCookieValue 方法。

CookieRequestCultureProviderDefaultCookieName 将返回用来跟踪用户首选区域性信息的默认 cookie 名称。 默认的 cookie 名称为 .AspNetCore.Culture。

cookie 格式为 c=%LANGCODE%|uic=%LANGCODE%，其中 c 是 Culture，uic 是 UICulture，例如：

c=en-UK|uic=en-US

如果只提供一种区域性信息或 UI 区域性，则提供的区域性同时用于区域性信息和 UI 区域性。

接受语言 HTTP 标题

接受语言标题在大多数浏览器中可设置，最初用于指定用户的语言。 此设置指示浏览器已设置为发送或已从基础操作系统继承的内容。 浏览器请求的接受语言 HTTP 标题不是检测用户首选语言的可靠方法（请参阅 Setting language preferences in a browser（在浏览器中设置首选项）。 生产应用应包括一种用户可以自定义区域性选择的方法。

在 Edge 中设置接受语言 HTTP 标题

1. 搜索“设置”中的“首选语言”。

2. 首选语言在“首选语言”框中列出。

3. 选择“添加语言”以添加到列表中。

4. 选择语言旁边的“更多操作...”以更改首选项的顺序。

Content-Language HTTP 标头

Content-Language 实体标头：

• 用于描述面向受众的语言。
• 允许用户根据用户的首选语言来区分。

实体标头用于 HTTP 请求和响应。

可通过设置属性 ApplyCurrentCultureToResponseHeaders 来添加 Content-Language 标头。

添加 Content-Language 标头：

• 允许 RequestLocalizationMiddleware 使用 CurrentUICulture 设置 Content-Language 标头。
• 无需显式设置响应标头 Content-Language。

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

应用 RouteDataRequest CultureProvider

RouteDataRequestCultureProvider 会根据 culture 路由值的值设置区域性。 请参阅 使用中间件作为筛选器的 URL 区域性提供程序 了解以下信息：

• 使用中间件作为 ASP.NET Core 的筛选器功能。
• 如何使用 RouteDataRequestCultureProvider 从 URL 设置应用的区域性。

有关如何在全局应用 RouteDataRequestCultureProvider 的信息，请参阅 使用中间件在全局应用 RouteDataRequest CultureProvider 作为筛选器。

使用自定义提供程序

假设你想要让客户在数据库中存储其语言和区域性。 你可以编写一个提供程序来查找用户的这些值。 下面的代码演示如何添加自定义提供程序：

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 查找区域性，然后再从查询字符串查找。

如前所述，通过将顺序设置为 0 的 AddInitialRequestCultureProvider 添加自定义提供程序，因此此提供程序优先于其他提供程序。

用户替代区域性

用户可使用 RequestLocalizationOptions.CultureInfoUseUserOverride 属性来决定是否为 CultureInfoDateTimeFormat 和 NumberFormat 属性使用非默认的 Windows 设置。 这对 Linux 没有影响。 这直接对应于 UseUserOverride。

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

以编程方式设置区域性

GitHub 上的示例项目 Localization.StarterWeb 包含设置 Culture 的 UI。 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 插入此项目的示例代码。 GitHub 上的 Localization.StarterWeb 项目包含的代码可通过依赖项注入容器将 RequestLocalizationOptions 流到 Razor 部分。

模型绑定路由数据和查询字符串

请参阅模型绑定路由数据和查询字符串的全球化行为。

后续步骤

本地化应用还涉及以下任务：

• 使应用内容可本地化。
• 为应用支持的语言和区域性提供本地化资源

其他资源

• 在 ASP.NET Core 中将中间件用作筛选器的 URL 区域性提供程序
• 将中间件用作筛选器的情况下全局应用 RouteDataRequest CultureProvider
• ASP.NET Core 全球化和本地化
• 使 ASP.NET Core 应用内容可本地化
• 在 ASP.NET Core 应用中针对语言和区域性提供本地化资源
• 对 ASP.NET Core 本地化进行故障排除
• 对 .NET 应用程序进行全球化和本地化
• 本文所用的 Localization.StarterWeb 项目。
• .resx 文件中的资源
• Microsoft 多语言应用工具包
• 本地化与泛型