ASP.NET Core 中文文件第三章原理（6）全球化與本地化

阿新 • • 發佈：2019-01-18

使用 ASP.NET Core 建立一個多語言版本的網站有助於你吸引到更多的使用者，ASP.NET Core 提供服務和中介軟體來支援本地化語言和文化。

國際化涉及全球化和本地化。全球化是為了應用程式支援不同文化而設計的。全球化增加了對特定地理區域的語言文字的輸入、顯示和輸出的支援。

本地化是針對一個特定的文化/區域，你早已經完成了本地化處理的全球化應用程式。欲瞭解更多資訊，請參閱文件尾部的 Globalization and localization terms 。

應用程式本地化包含以下內容：

讓應用程式的內容本地化。
為不同的文化和語言提供本地化資源包。
在每個請求中實現語言/文化切換策略。

讓應用程式的內容本地化

在 ASP.NET Core 中， IStringLocalizer 以及 IStringLocalizer 的架構在開發本地化應用程式時為提高生產力的手段。IStringLocalizer 使用 ResourceManager 和 ResourceReader 在執行時提供指定文化的資原始檔。IStringLocalizer 是一個實現了 IEnumerable 的簡單介面並且擁有索引器來來返回本地化的字串。IStringLocalizer 並不需要你把預設語言字串儲存在資原始檔中。你可以針對某個特定的語言開發應用程式，而不是需要在開發早期建立資原始檔。下面的程式碼演示瞭如何包裝字串 “About Title” 本地化。

using Microsoft.AspNet.Mvc;
using Microsoft.Extensions.Localization;

namespace Localization.StarterWeb.Controllers
{
    [Route("api/[controller]")]
    public class AboutController : Controller
    {
        private readonly IStringLocalizer<AboutController> _localizer;

        public AboutController(IStringLocalizer<AboutController> localizer)
        {
            _localizer = localizer;
        }

        [HttpGet]
        public string Get()
        {
            return _localizer["About Title"];
        }
    }
}

在上面的程式碼中，IStringLocalizer<T> 實現了 Dependency Injection。如果沒有發現 “About Title” 的本地化值，則索引的鍵值被返回，即是字串 “About Title” 。你可以在應用程式中保留預設語言文字字串，然後再使用 localizer 包裝他們，這樣你就可以專注於開發應用程式。使用預設語言開發應用併為進行本地化的步驟做準備，同時無需事先建立一個預設的資原始檔。另外，你也可以使用傳統的方法，一鍵恢復預設語言的字串。對於大部分開發者來說新的工作流程無需一個預設語言的 .resx 檔案，並且簡單地包裝字串可以減少本地化的應用程式的工作量。其他開發者會選擇傳統的工作流程，因為它可以更容易地與長字串文字工作，並使其更易於更新本地化字串。

使用 IHtmlLocalizer 來處理包含 HTML 的資原始檔， IHtmlLocalizer 對格式化過的資源字串引數進行編碼，而不是對原始資源字串。下面例子中的高亮程式碼，只有 name 引數的值被 HTML 編碼。

using System;
using Microsoft.AspNet.Http;
using Microsoft.AspNet.Localization;
using Microsoft.AspNet.Mvc;
using Microsoft.AspNet.Mvc.Localization;

namespace Localization.StarterWeb.Controllers
{
    public class BookController : Controller
    {
        private readonly IHtmlLocalizer<BookController> _localizer;

        public BookController(IHtmlLocalizer<BookController> localizer)
        {
            _localizer = localizer;
        }

        public IActionResult Hello(string name)
        {
            ViewData["Message"] = _localizer["<b>Hello</b><i> {0}</i>", name];

            return View();
        }

提示:你通常只想本地化文字而非HTML。

在最低層次, 你可以通過 Dependency Injection 獲取 IStringLocalizerFactory：

 public class TestController : Controller
 {
     private readonly IStringLocalizer _localizer;
     private readonly IStringLocalizer _localizer2;

     public TestController(IStringLocalizerFactory factory)
     {
         _localizer = factory.Create(typeof(SharedResource));
         _localizer2 = factory.Create("SharedResource", location: null);
     }       

     public IActionResult About()
     {
         ViewData["Message"] = _localizer["Your application description page."] 
             + " loc 2: " + _localizer2["Your application description page."];

         return View();
     }

上面的程式碼演示了兩個不同的工廠建立方法。

你可以通過控制器、區域劃分本地化字串，或者都包含在一個容器中。在示例應用程式中，名為 SharedResource 的 dummy 類被用於共享資源。

// Dummy class to group shared resources

namespace Localization.StarterWeb
{
    public class SharedResource
    {
    }
}

一些開發人員使用 Startup 類來包含全域性或共享字串。在下面的例子中，展示了 InfoController 以及 SharedResource 本地化使用：

 public class InfoController : Controller
 {
     private readonly IStringLocalizer<InfoController> _localizer;
     private readonly IStringLocalizer<SharedResource> _sharedLocalizer;

     public InfoController(IStringLocalizer<InfoController> localizer,
                    IStringLocalizer<SharedResource> sharedLocalizer)
     {
         _localizer = localizer;
         _sharedLocalizer = sharedLocalizer;
     }

     public string TestLoc()
     {
         string msg = "Shared resx: " + _sharedLocalizer["Hello!"] +
                      " Info resx " + _localizer["Hello!"];
         return msg;
     }

檢視本地化

IViewLocalizer 服務為檢視提供本地化字串。 ViewLocalizer 類實現了這個介面，並且根據檢視檔案的路徑來查詢資源。下面的程式碼演示瞭如何使用 IViewLocalizer 的預設實現：

@using Microsoft.AspNet.Mvc.Localization

@inject IViewLocalizer Localizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<p>@Localizer["Use this area to provide additional information."]</p>

IViewLocalizer 的預設實現基於檢視的檔名稱來查詢資原始檔。沒有使用全域性共享的資原始檔的可選項。 ViewLocalizer 使用 IHtmlLocalizer 實現本地化，所以 Razor 模版不會 HTML 編碼本地化字串。你可以使用引數傳遞資源字串並且 IViewLocalizer 會HTML 編碼引數，而不是資源字串。參考下面的 Razor 標籤程式碼：

@Localizer["<i>Hello</i> <b>{0}!</b>", UserManager.GetUserName(User)]

法語資原始檔會包含如下內容：

鍵	值
< i>Hello< /i > < b>{0}!< /b>	< i>Bonjour< /i > < b>{0}!< /b >

渲染檢視將包含資原始檔中的 HTML 標籤。

提示：你通常只想本地化文字而非HTML。

@using Microsoft.AspNet.Mvc.Localization
@using Localization.StarterWeb.Services

@inject IViewLocalizer Localizer
@inject IHtmlLocalizer<SharedResource> SharedLocalizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>

<h1>@SharedLocalizer["Hello!"]</h1>

DataAnnotations 本地化

使用 IStringLocalizer 本地化 DataAnnotations 錯誤資訊。使用選項ResourcesPath = "Resources"， RegisterViewModel 中的錯誤資訊會儲存到以下路徑中：

Resources/ViewModels.Account.RegisterViewModel.fr.resx
Resources/ViewModels/Account/RegisterViewModel.fr.resx

 public class RegisterViewModel
 {
     [Required(ErrorMessage = "The Email field is required.")]
     [EmailAddress(ErrorMessage = "The Email field is not a valid e-mail address.")]
     [Display(Name = "Email")]
     public string Email { get; set; }

     [Required(ErrorMessage = "The Password field is required.")]
     [StringLength(8, ErrorMessage = "The {0} must be at least {2} characters long.", MinimumLength = 6)]
     [DataType(DataType.Password)]
     [Display(Name = "Password")]
     public string Password { get; set; }

     [DataType(DataType.Password)]
     [Display(Name = "Confirm password")]
     [Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
     public string ConfirmPassword { get; set; }
 }

執行時不支援從非驗證屬性中查詢本地化字串。在上面的程式碼裡，“Email”（來自 [Display(Name = "Email")]）將不會被本地化。

為你的語言和文化提供本地化資源支援

SupportedCultures（文化支援）以及 SupportedUICultures（UI文化支援）

ASP.NET Core 允許你指定兩個文化值， SupportedCultures 以及SupportedUICultures。SupportedCultures 的 CultureInfo 物件決定了和文化相關的函式，如日期，時間，數字和貨幣格式的結果。 SupportedCultures 同時決定了文字如何排序，大小寫轉換以及字串比較。參考CultureInfo.CurrentCulture 獲取更多關於伺服器如何獲取文化的資訊。SupportedUICultures 決定如何通過 ResourceManager 查詢翻譯字串（從 .resx 檔案）。 ResourceManager
只是通過 CurrentUICulture 簡單的查詢指定文化的字串。.NET 的每個執行緒都會擁有 CurrentCulture 和CurrentUICulture 物件。當 ASP.NET Core 在渲染與文化相關的函式的時候會檢視這些物件值。例如，如果當前執行緒的區域性設定為 “en-US” （英語、美國）， DateTime.Now.ToLongDateString() "Thursday, February 18, 2016" ，但如果 CurrentCulture 設定為 “es-ES”（西班牙語、西班牙），輸出將會是 “jueves, 18 de febrero de 2016”。

使用資原始檔

資原始檔是一種從程式碼中分離本地化字串的有效機制。非預設語言翻譯字串被隔離到 .resx 資原始檔中。例如，你可能希望建立一個名為Welcome.es.resx 的西班牙語資原始檔來包含翻譯字串。“es”是西班牙語的語言編碼。在Visual Studio中，這樣建立資原始檔：

在 Solution Explorer 中，右擊包含資原始檔的目錄 > Add > New Item 。
在 Search installed templates 對話方塊中，輸入 “resource” 並且命名檔案。
在 Name 列輸入鍵值（本地字串）在 Value 列輸入翻譯值。

Visual Studio 展示出 Welcome.es.resx 檔案。

使用 Visual Studio 建立資原始檔

如果你在 Visual Studio 中建立一個資原始檔，而且檔名中不存在文化資訊（例如，Welcome.resx），Visual Studio 將會為之建立一個 C# 類並且為每個字串建立一個欄位。這通常不是你想要的 ASP.NET Core 的方式；通常你不會有一個預設的 .resx 資原始檔（檔名不包含文化資訊的 .resx 檔案）。我們建議你建立帶有文化名稱的 .resx（例如：Welcome.fr.resx ）檔案。當你建立一個與文化資訊關聯的 .resx 時，Visual Studio 不會產生類檔案。按照我們預期大部分開發者不會建立預設語言資原始檔。

新增其他文化

每一種語言和文化的結合（除了預設語言外）需要一個獨特的資原始檔。你可以為不同的文化和語言環境建立新的資原始檔，ISO 語言程式碼作為檔名的一部分（例如， en-us 、 fr-ca 以及 en-gb）。這些 ISO 語言程式碼放置在檔名和 .resx 副檔名之間，如 Welcome.es-MX.resx （西班牙語/墨西哥）。要指定文化中性語言，你可以消除國家程式碼，如 Welcome.fr.resx 為法語。

為每個請求提供語言文化選擇功能的實施策略

配置本地化

在 ConfigureServices 方法中本地化的配置：

  public void ConfigureServices(IServiceCollection services)
  {

      services.AddLocalization(options => options.ResourcesPath = "Resources");

      services.AddMvc()
        .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
        .AddDataAnnotationsLocalization();

AddLocalization 在服務容器中新增本地化服務。上述程式碼同時把資原始檔路徑設定到 “Resources”。
AddViewLocalization 新增本地化檢視檔案支援。在這個示例中檢視本地化是基於檢視檔案字尾的。例如： Index.fr.cshtml 中的 “fr”。
AddDataAnnotationsLocalization 增加了通過 IStringLocalizer 來抽象支援本地化 DataAnnotations 驗證訊息。

本地化中介軟體

在請求中的當前的文化是在本地化 Middleware 中設定的。本地化中介軟體在Startup.cs 檔案的 Configure 方法中啟用。

  public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)

      var supportedCultures = new[]
      {
          new CultureInfo("en-US"),
          new CultureInfo("en-AU"),
          new CultureInfo("en-GB"),
          new CultureInfo("en"),
          new CultureInfo("es-ES"),
          new CultureInfo("es-MX"),
          new CultureInfo("es"),
          new CultureInfo("fr-FR"),
          new CultureInfo("fr"),
      };

      app.UseRequestLocalization(new RequestLocalizationOptions
      {
          DefaultRequestCulture = new RequestCulture("en-US"),
          // Formatting numbers, dates, etc.
          SupportedCultures = supportedCultures,
          // UI strings that we have localized.
          SupportedUICultures = supportedCultures
      });

      // Remaining code omitted for brevity.

UseRequestLocalization 初始化一個 RequestLocalizationOptions 物件。在每次請求裡 RequestLocalizationOptions 的 RequestCultureProvider 列表會被遍歷，第一個provider 會被使用來判斷請求使用的文化。預設的 provider 來自RequestLocalizationOptions 類：

預設列表從最具體的到最不具體的。後面的文章中我會告訴你如何更改順序，甚至新增自定義的本地化 provider。如果沒有非空的 provider，DefaultRequestCulture 被使用。

QueryStringRequestCultureProvider

有些應用程式會使用一個查詢字串來設定區域性和 UI 區域性。對於使用 cookie 或者 Accept-Language 頭的方法的應用程式，在 URL 上增加查詢字串有助於除錯和測試程式碼。除非你修改 RequestCultureProvider 列表，否則查詢字串引數永遠是用來指定本地化 provider 的。你可在查詢字串引數中傳遞 culture 以及 ui-culture 引數。下面的例子指定了具體的區域性（語言和區域）設定為西班牙語/墨西哥：

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

如果你僅僅使用（culture 或者 ui-culture）中的一個引數進行傳遞，查詢字串 provider 將使用你傳遞一個值來設定這兩個引數。例如，僅設定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 為區域資訊和 uic 為 UI 區域資訊，例如：

c=’en-UK’|uic=’en-US’

如果僅指定 culture 或 UI culture中的一個，指定的區域性資訊將同時用於 culture和 UI culture。

HTTP Accept-Language HTTP 頭資訊

大多數瀏覽器支援設定 Accept-Language header 頭資訊，這個設定最初的目的是為了指定使用者的語言。指示什麼型別的瀏覽器已被設定且傳送或已經從底層作業系統繼承。從瀏覽器請求的 Accept-Language HTTP 標頭來檢測使用者的首選語言容易產生錯誤（請參見在瀏覽器中設定語言首選項）。生產環境中應用程式應該包括一種方法讓使用者自己選擇的區域性資訊。

在 IE 瀏覽器中設定 Accept-Language HTTP 頭資訊

在齒輪圖示選單中, 點選 Internet Options。
點選 Languages。
點選 Set Language Preferences。
點選 Add a language。
新增語言。
點選語言, 然後點選 Move Up。

使用自定義 provider

假設你想要在資料庫裡面儲存客戶的語言和文化資訊。你可以寫一個 provider 來查詢這些使用者的值。下面的程式碼演示如何新增自定義 provider：

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: "en-US", uiCulture: "en-US");
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>
    {
       // My custom request culture logic
      return new ProviderCultureResult("en");
    }));
});

使用 RequestLocalizationOptions 新增或者刪除本地化 providers。

資原始檔命名

資源被命名為資原始檔的類名減去預設名稱空間（一般是應用程式集名稱）。例如 LocalizationWebsite.Web 專案 LocalizationWebsite.Web.Startup 類的法語的資源將被命名為 Startup.fr.resx。

LocalizationWebsite.Web.Controllers.HomeController 類則是Controllers.HomeController.fr.resx。如果出於某種原因，你的目標類是不是在預設的名稱空間，你將需要完整的型別名稱。例如，在示例專案型別 ExtraNamespace.Tools 類會使用 ExtraNamespace.Tools.fr.resx 。

在示例專案中， ConfigureServices 方法將 ResourcesPath 設定為 “Resources”，所以對於 home controller 的法語資原始檔的專案相對路徑是 Resources/Controllers.HomeController.fr.resx。另外，你也可以使用資料夾來組織資原始檔。對於 home controller ，路徑將是Resources/Controllers/HomeController.fr.resx。如果不使用 ResourcesPath 可選項， .resx 檔案會包含在專案的根目錄。 HomeController 的資原始檔將被命名為 Controllers.HomeController.fr.resx。選擇使用點或路徑命名約定的選擇取決於你想如何組織你的資原始檔。

資原始檔	點或路徑命名
Resources/Controllers.HomeController.fr.resx	點
Resources/Controllers/HomeController.fr.resx	路徑

資原始檔在 Razor 檢視中使用類似 @inject IViewLocalizer 模式來呼叫。對於檢視的資原始檔可以使用點命名或路徑命名的方式進行命名。Razor 檢視資原始檔名參照其關聯檢視檔案路徑。假設我們設定 ResourcesPath 為 “Resources”，關聯檢視 Views/Book/About.cshtml 的法語資原始檔將會如下所示：

Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx

如果你不設定 ResourcesPath 選項，檢視的 .resx 檔案將與檢視檔案位於同一資料夾內。

如果你刪除了 “.fr” 區域性標誌但是你又把當前區域性資訊設定為法語（通過 Cookie 或其他機制），預設的資原始檔將會被讀取出來用以字串本地化。當在你的伺服器上找不到對應你的請求區域性資訊的資原始檔的時候，資源管理器會指定指定預設或備份資源。如果你想在缺少資源請求的文化時能返回鍵值，你不能有一個預設的資原始檔。

程式設計方式設定文化

GitHub 上的示例專案 Localization.StarterWeb 包含使用者介面來設定 Culture。 Views/Shared/_SelectLanguagePartial.cshtml 檔案允許你從支援的區域性列表中選擇區域：

@using Microsoft.AspNet.Builder
@using Microsoft.AspNet.Http.Features
@using Microsoft.AspNet.Localization
@using Microsoft.AspNet.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();
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@Context.Request.Path" 
          method="post" class="form-horizontal" role="form">
        @Localizer["Language:"] <select name="culture"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Views/Shared/_SelectLanguagePartial.cshtml 檔案新增到佈局檔案的 footer
區域，因此將提供給所有檢視使用：

  <div class="container body-content">
      @RenderBody()
      <hr />
      <footer>
          <div class="row">
              <div class="col-md-6">
                  <p>&copy; 2015 - Localization.StarterWeb</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 區域性模版。

本地化全球化術語

本地化你的應用程式的過程也需要對現代軟體開發中常用的相關字符集的有一個基本的瞭解，並熟悉與之相關的問題。儘管所有的計算機把文字儲存為數字（編碼），不同的系統使用不同的數字儲存相同的文字。本地化程序是指代通過指定的文化/區域設定來翻譯應用程式的使用者介面（UI）。

Localizability 是用於驗證一個全球化的應用程式已經準備好本地化的一個即時流程。

區域性名稱的 RFC 4646 格式為 “-” ，其中是語言程式碼，是子文化程式碼。例如，es-CL 西班牙語（智利）， en-US 是指英語（美國）， en-AU則是英語（澳大利亞）。 RFC 4646 是用與語言相關的ISO 639雙字母小寫區域性程式碼和一個與國家或地區相關的ISO3166雙字母大寫子程式碼組合。詳見Language Culture Name。

國際化通常縮寫為 “I18N”。縮寫採取首字母和尾字母以及它們之間的字母數，所以 18 代表首字母 “I” 和尾字母 “N” 之間的字母數。這同樣適用於全球化（G11N）和本地化（L10N）。

術語：

Globalization（全球化） (G11N)：讓你的應用程式支援多種語言和區域設定。
Localization（本地化） (L10N)：讓你的應用程式支援某一種特定語言/區域設定。
Internationalization（國際化） (I18N)：是全球化和本地化的結合。
Culture（文化）：指代語言和可選地區。
Neutral culture（非特定區域文化）：指代某種語言，不包含區域。（如 “en”、”es”）
Specific culture（特定區域文化）：指代某種語言和區域的組合。（如 “en-US”、”en-GB”、”es-CL”）
Locale（區域設定）：區域設定和檔案是相同的。

ASP.NET Core 中文文件 第三章 原理（6）全球化與本地化