在當地語系化的 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 或 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

如果只提供其中一個文化特性資訊或 UI 文化特性，則提供的文化特性同時用於文化特性資訊和 UI 文化特性。

Accept-Language HTTP 標頭

您可在大多數的瀏覽器中設定 Accept-Language 標頭，其最初的設計目的是用來指定使用者的語言。 這項設定可指出瀏覽器已設好要傳送哪些項目，或已從基礎作業系統繼承哪些項目。 透過瀏覽器要求的 Accept-Language HTTP 標頭來偵測使用者的慣用語言，並非萬無一失 (請參閱 Setting language preferences in a browser (在瀏覽器中設定語言喜好設定)。 生產環境應用程式應該包含可讓使用者自訂文化特性的選擇方式。

在 Edge 中設定 Accept-Language 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 尋找文化特性，然後是查詢字串。

如先前所述，透過 AddInitialRequestCultureProvider 新增自訂提供者，以將順序設定為 0，因此此提供者的優先順序會高於其他提供者。

使用者覆寫文化特性

RequestLocalizationOptions.CultureInfoUseUserOverride 屬性可讓應用程式決定是否針對 CultureInfo DateTimeFormat 和 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 多語應用程式工具組
• 當地語系化和泛型