asp.net core 實作支持多語言

Intro

最近有一個外國友人通過郵件聯系我，想用我的活動室預約，但是還沒支持多語言，基本上都是寫死的中文，所以最近想支持一下更多語言，于是有了多語言方面的一些實踐

國際化/本地化介紹

國際化（Globalization）和本地化（Localization）是要實作的多語言支持的基礎

Globalization is the process of designing and developing applications that function for multiple cultures.

Localization is the process of customizing your application for a given culture and locale.

國際化是要支持處理多種文化，而本地化是要根據某一個文化和區域的來展示相應的處理，

更多關于國際化與本地化的不同可以參考 Stack Overflow 上的討論 https://stackoverflow.com/questions/2074869/globalization-vs-localization

Localization In Asp.NET Core

微軟官方的 Localization 的實作是基于資源檔案實作的 (*.resx)，我們也可以擴展支持更多方式，如 JSON/資料庫 都是可以的，社區已經有實作的示例，只要是可以提供一個文本源的都是可以的，我們先使用默認的基于資源檔案的，下一篇再講一個自定義實作一個 Localization Provider，

.NET Core Localization 的 核心是 IStringLocalizer，asp.net core 里擴展定義了 IViewLocalizer 和 IHtmlLocalizer，IViewLocalizer 和 IHtmlLocalizer 主要是為了處理包含 html 的資源，他們不會對資源進行 html encode，相當于 @Html.Raw 的效果，而 IStringLocalizer 則會被 html encode，除此之外 IViewLocalizer 還會根據當前視圖的路徑尋找資源檔案

來看一個示例：

Razor 頁面

瀏覽器效果：

查看網頁源代碼：

實際案例

服務注冊

注冊 Localization 相關服務：

var supportedCultures = new[]
{
    new CultureInfo("zh"),
    new CultureInfo("en"),
};
services.Configure<RequestLocalizationOptions>(options =>
{
    options.DefaultRequestCulture = new RequestCulture("zh");
    // Formatting numbers, dates, etc.
    options.SupportedCultures = supportedCultures;
    // UI strings that we have localized.
    options.SupportedUICultures = supportedCultures;
});
services.AddLocalization(options => options.ResourcesPath = Configuration.GetAppSetting("ResourcesPath"));

配置視圖 Localization（根據需要如果是 WebAPI 就不需要了）

services.AddControllersWithViews()
   .AddNewtonsoftJson(options =>
   {
       options.SerializerSettings.ContractResolver = new DefaultContractResolver();
       options.SerializerSettings.DateTimeZoneHandling = DateTimeZoneHandling.Utc; // 設定時區為 UTC
       options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;
       options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;
   })
    .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix,
                         opts => { opts.ResourcesPath = Configuration.GetAppSetting("ResourcesPath"); })
    .AddDataAnnotationsLocalization()
    .SetCompatibilityVersion(CompatibilityVersion.Latest);

中間件配置：

app.UseRequestLocalization();

邏輯代碼中使用示例：

IStringLocalizer 和 IHtmlLocalizer /IViewLocalizer 都可以直接從依賴注入服務中獲取，IStringLocalizer 和 IHtmlLocalizer 推薦使用強型別的方式，也就是下面示例的使用方式，使用方式和 ILogger 類似

public async Task<ActionResult> MakeReservation(
    [FromBody]ReservationViewModel model,
    [FromHeader]string captcha,
    [FromHeader]string captchaType,
    [FromServices]IStringLocalizer<HomeController> localizer)
{
    var result = new ResultModel<bool>();
    var isCodeValid = await HttpContext.RequestServices.GetService<CaptchaVerifyHelper>()
        .ValidateVerifyCodeAsync(captchaType, captcha);
    if (!isCodeValid)
    {
        result.Status = ResultStatus.RequestError;
        result.ErrorMsg = localizer["InvalidCaptchaInfo"];
        return Json(result);
    }

在視圖中使用示例：

localizer["data"] 回傳的是一個 LocalizedString，實作了隱式轉換為 string， 有的時候可能需要強制轉一下string， 或者使用 Value 屬性

@inject IViewLocalizer viewLocalizer
viewLocalizer["About"]

@Html.ActionLink((string)viewLocalizer["About"], "About", "Home")
@Html.ActionLink(viewLocalizer["About"].Value, "About", "Home")

資源檔案配置：

資源檔案的配置和檔案的結構類似，下面是一個示例

準備的來說是和型別的 FullName 有關系，一般的專案名稱就是程式集名稱，就是根命名空間，檔案名稱就是型別名稱，所以一般情況下資源檔案的位置和型別的位置是一致的，但是如果檔案和型別名稱不符合，那就要按照型別的 FullName 來找，視圖也是類似的，如果根命名空間不是程式集名稱，也是可以配置的具體的參考檔案

Controllers.HomeController => Controllers/HomeController.zh.resx/Controllers/HomeController.en.resx

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

實際專案中的資源檔案示例：

實際訪問效果：https://reservation.weihanli.xyz/

默認的中文界面：

英文界面：

只是做了幾個前臺的示例，還有很多地方沒改

Docker 部署

現在的專案是基于 docker + k8s 部署的，所以支持 docker 部署很重要

要支持多語言，需要安裝 ICU 相關的包，（這個可不是 996.icu 的 icu 哈，如果不裝真的有可能導致 996.icu）

RUN apk add --no-cache icu-libs # 安裝 icu-libs
ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT false # 配置 Globalization

完整的 dockerfile 可以參考：
https://github.com/dotnet/dotnet-docker/blob/cb7a9c35dacf6d34fcf7bab7995e60faef55f61f/samples/dotnetapp/Dockerfile.alpine-x64-globalization

More

.net core 的設計真的是很靈活，很優美，基于資源檔案的本地化，感覺不太方便，使用資源檔案的化可能就只能使用 VS 編輯了，雖然也是純文本的，基于 xml 但是編輯起來不如界面看著編輯舒服，如果使用 json 之類的，就比較簡單明了，編輯起來也比較方便，所以想把資源檔案替換成 JSON 檔案

下次分享一篇基于 JSON 的 Localization Provider 的實作

Reference

• https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization?view=aspnetcore-3.1
• https://github.com/dotnet/extensions/tree/master/src/Localization
• https://github.com/dotnet/aspnetcore/tree/master/src/Middleware/Localization
• https://stackoverflow.com/questions/2074869/globalization-vs-localization
• https://github.com/WeihanLi/ActivityReservation

標籤：.NET Core

上一篇：初學c#，老師布置的作業最后常規地址不會，求各路大神能把代碼寫出來

下一篇：NetCore 啟動地址配置詳解