[Abp 源碼分析]十3、多語言(本地化)處理

時間  2019-11-08
標籤 abp 源碼 分析 多語言 本地化 處理 简体版
原文   原文鏈接

0.簡介

若是你所開發的須要走向世界的話，那麼確定須要針對每個用戶進行不一樣的本地化處理，有可能你的客戶在日本，須要使用日語做爲顯示文本，也有可能你的客戶在美國，須要使用英語做爲顯示文本。若是你仍是同樣的寫死錯誤信息，或者描述信息，那麼就沒法作到多語言適配。html

Abp 框架自己提供了一套多語言機制來幫助咱們實現本地化，基本思路是 Abp 自己維護一個鍵值對集合。只須要將展現給客戶的文字信息處都使用一個語言 Key 來進行填充，當用戶登陸系統以後，會取得當前用戶的區域文化信息進行文本渲染。前端

0.1 如何使用

咱們首先來看一下如何定義一個多語言資源並使用。首先 Abp 自身支持三種類型的本地化資源來源，第一種是 XML 文件，第二種則是 JSON 文件，第三種則是內嵌資源文件，若是這三種都不能知足你的需求，你能夠自行實現 ILocalizationSource  接口來返回多語言資源。數據庫

小提示：app

Abp Zero 模塊就提供了數據庫持久化存儲多語言資源的功能。框架

0.1.1 定義應用程序支持的語言

若是你須要爲你的應用程序添加不一樣語言的支持，就必須在你任意模塊的預加載方法當中添加語言來進行配置：ide

Configuration.Localization.Languages.Add(new LanguageInfo("en", "English", "famfamfam-flag-england", true));
Configuration.Localization.Languages.Add(new LanguageInfo("tr", "Türkçe", "famfamfam-flag-tr"));

例如以上代碼，就可以讓咱們的程序擁有針對英語與土耳其語的多語言處理能力。ui

這裏的 famfamfam-flag-england 與 famfamfam-flag-tr 是一個 CSS 類型，是 Abp 爲前端展現所封裝的小國旗圖標。3d

0.1.2 創建多語言資源文件

有了語言以後，Abp 還須要你提供標準的多語言資源文件，這裏咱們以 自帶的 XML 資源文件爲例，其文件名稱爲 Abp-zh-Hans.xml ，路徑爲 Abp\Localization\Sources\AbpXmlSource。code

<?xml version="1.0" encoding="utf-8" ?>
<localizationDictionary culture="zh-Hans">
  <texts>
    <text name="SmtpHost">SMTP主機</text>
    <text name="SmtpPort">SMTP端口</text>
    <text name="Username">用戶名</text>
    <text name="Password">密碼</text>
    <text name="DomainName">域名</text>
    <text name="UseSSL">使用SSL</text>
    <text name="UseDefaultCredentials">使用默認驗證</text>
    <text name="DefaultFromSenderEmailAddress">默認發件人郵箱地址</text>
    <text name="DefaultFromSenderDisplayName">默認發件人名字</text>
    <text name="DefaultLanguage">預設語言</text>
    <text name="ReceiveNotifications">接收通知</text>
    <text name="CurrentUserDidNotLoginToTheApplication">當前用戶沒有登陸到系統！</text>
    <text name="TimeZone">時區</text>
    <text name="AllOfThesePermissionsMustBeGranted">您沒有權限進行此操做,您須要如下權限: {0}</text>
    <text name="AtLeastOneOfThesePermissionsMustBeGranted">您沒有權限進行此操做,您至少須要下列權限的其中一項: {0}</text>
    <text name="MainMenu">主菜單</text>
  </texts>
</localizationDictionary>

每一個文件內部，會有一個 <localizationDictionary culture="zh-Hans"> 節點用於說明當前文件是針對於哪一個區域適用的，而在其 <texts> 內部則就是結合鍵值對的形式，name 裏面的內容就是多語言文本項的鍵，在標籤內部的就是其真正的值。xml

打開一個針對俄語國家的 XML 資源文件，文件名稱叫作 Abp-ru.xml。

<?xml version="1.0" encoding="utf-8" ?>
<localizationDictionary culture="ru">
  <texts>
    <text name="SmtpHost">SMTP сервер</text>
    <text name="SmtpPort">SMTP порт</text>
    <text name="Username">Имя пользователя</text>
    <text name="Password">Пароль</text>
    <text name="DomainName">Домен</text>
    <text name="UseSSL">Использовать SSL</text>
    <text name="UseDefaultCredentials">Использовать учетные данные по умолчанию</text>
    <text name="DefaultFromSenderEmailAddress">Электронный адрес отправителя по умолчанию</text>
    <text name="DefaultFromSenderDisplayName">Имя отправителя по умолчанию</text>
    <text name="DefaultLanguage">Язык по умолчанию</text>
    <text name="ReceiveNotifications">Получать уведомления</text>
    <text name="CurrentUserDidNotLoginToTheApplication">Текущий пользователь не вошёл в приложение!</text>
  </texts>
</localizationDictionary>

能夠看到 Key 值都是同樣的，只是其 <text> 內部的值根據區域國家的不一樣值不同而已。

其次從文件名咱們就能夠看到須要使用 XML 資源文件對於文件的命名格式會有必定要求，仍是以 Abp 自帶的資源文件爲例，能夠看一下他們基本上都是由 {SourceName}-{CultureInfo}.xml 這樣構成的。

0.1.3 註冊本地化的 XML 資源

那麼若是咱們須要註冊以前的兩個 XML 資源到 Abp 框架當中的話，則須要在預加載模塊處經過以下代碼來執行註冊，而且須要右鍵 XML 文件，更改其構建操做爲 內嵌資源。

Configuration.Localization.Sources.Add(
    new DictionaryBasedLocalizationSource(
        // 本地化資源名稱
        AbpConsts.LocalizationSourceName,
        // 數據源提供者，這裏使用的是 XML ，除了 XML 提供者，還有 JSON 等
        new XmlEmbeddedFileLocalizationDictionaryProvider(
            typeof(AbpKernelModule).GetAssembly(), "Abp.Localization.Sources.AbpXmlSource"
        )));

0.1.4 獲取多語言文本

若是你須要在某處獲取指定 Key 所對應的具體顯示文本，只須要注入 ILocalizationManager ，經過其 GetString() 方法就能夠得到具體的值。若是你須要獲取本地化資源的地方不可以使用依賴注入，你可使用 LocalizationHelper 靜態類來進行操做。

var @string = _localizationManager.GetString("Abp", "MainMenu");

它默認是從 Thread.CurrentThread.CurrentUICulture 獲取到的當前區域信息，從而來取得某個 Key 所對應的顯示值，而當前區域信息是由 Abp 注入的一系列 RequestCultureProviders 所提供的，他按照如下順序來進行設置。

  1. QueryStringRequestCultureProvider(ASP .NET Core 默認提供)：該默認提供器使用的是 QueryString 的 culture&ui-culture 所提供的區域文化信息來初始化該值，例如：culture=es-MX&ui-culture=es-MX。
  2. AbpUserRequestCultureProvider (Abp 提供)：該提供器會讀取當前用戶的 IAbpSession 信息，而且從 ISettingManager 中獲取用戶所配置的 "Abp.Localization.DefaultLanguageName" 屬性，將其做爲默認的區域文化信息。
  3. AbpLocalizationHeaderRequestCultureProvider (Abp 提供)：使用每次請求頭當中的 .AspNetCore.Culture 值做爲當前的區域文化信息，例如 c=en|uic=en-US。
  4. CookieRequestCultureProvider (ASP .NET Core 提供)：使用每次請求的 Cookie 當中 Key 爲 .AspNetCore.Culture 值做爲當前區域文化信息。
  5. AbpDefaultRequestCultureProvider (Abp 提供)：若是以前這些提供器都沒有爲當前區域文化賦值，則從 ISettingMananger 當中取得 Abp.Localization.DefaultLanguageName 的默認值。
  6. AcceptLanguageHeaderRequestCultureProvider (ASP .NET Core 默認提供)：該提供器最終會使用用戶每次請求時傳遞的 Accept-Language 頭部做爲當前區域文化信息。

小提示：

這裏 Abp 注入的提供器是有順序的，注入這麼多提供器就是爲了最後肯定當前用戶的區域文化信息以便展現相應的語言文本。

1.啓動流程

1.1 啓動流程圖

1.2 代碼流程

根據使用方法咱們能夠得知，要配置 Abp 的多語言，必須得等 IAbpStartupConfiguration 初始化完畢才能夠。即在 AbpBootstrapper 的 Initialize() 方法之中：

public virtual void Initialize()
{
    // ... 其餘代碼
    // 注入 IAbpStartupConfiguration 配置與本地化資源配置
    IocManager.IocContainer.Install(new AbpCoreInstaller());

    // ... 其餘代碼
    // 初始化 AbpStartupConfiguration 類型
    IocManager.Resolve<AbpStartupConfiguration>().Initialize();

    // ... 其餘代碼
}

配置類裏面包含了用戶所配置的全部語言與多語言資源信息，在被成功注入到 Ioc 容器以後，Abp 就開始使用本地化資源管理器來初始化這些多語言數據了。

public override void PostInitialize()
{
    // 註冊缺乏的組件，防止遺漏註冊組件
    RegisterMissingComponents();

    IocManager.Resolve<SettingDefinitionManager>().Initialize();
    IocManager.Resolve<FeatureManager>().Initialize();
    IocManager.Resolve<PermissionManager>().Initialize();
    
    // 重點在這裏，這個 PostInitialize 方法是存放在覈心模塊當中的，在這裏調用了本地化資源管理器的初始化方法
    IocManager.Resolve<LocalizationManager>().Initialize();
    IocManager.Resolve<NotificationDefinitionManager>().Initialize();
    IocManager.Resolve<NavigationManager>().Initialize();

    if (Configuration.BackgroundJobs.IsJobExecutionEnabled)
    {
        var workerManager = IocManager.Resolve<IBackgroundWorkerManager>();
        workerManager.Start();
        workerManager.Add(IocManager.Resolve<IBackgroundJobManager>());
    }
}

具體 LocalizationManager 及其內部的實現咱們在下一節代碼分析中詳細進行講述。

這些動做僅僅是在注入 Abp 框架的時候所須要執行的一些步驟，若是你要啓用多語言，須要在 ASP .NET Core 程序的 Startup 類中的 Configure() 處經過更改 UseAbpRequestLocalization 狀態爲 True，纔會將區域文化識別中間件注入到程序當中。

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    app.UseAbp(options =>
    {
        options.UseAbpRequestLocalization = false; //disable automatic adding of request localization
    });

    //...authentication middleware(s)

    app.UseAbpRequestLocalization(); //manually add request localization

    //...other middlewares

    app.UseMvc(routes =>
    {
        //...
    });
}

其實這裏的 UseAbpRequestLocalization() 就已經將上文說的那些 RequestProvider 按照順序依次注入到 MVC 之中了。

2.代碼分析

Abp 框架針對本地化處理相關的類型與方法定義都存放在 Abp 庫的 Localization 文件夾下。關係仍是相對複雜的，這裏咱們先從其核心的 Abp 庫針對於多語言的處理開始講起。

2.1 多語言模塊配置

Abp 須要使用的全部信息都是由用戶在本身啓動模塊的 PreInitialize() 當中，經過 ILocalizationConfiguration 進行注入配置。也就是說在 ILocalizationConfiguration 內部，主要是包含了語言，與多語言資源提供者兩種重點信息。

public interface ILocalizationConfiguration
{
    // 當前應用程序可配置的語言列表
    IList<LanguageInfo> Languages { get; }

    // 本地化資源列表
    ILocalizationSourceList Sources { get; }

    // 是否啓用多語言(本地化) 系統
    bool IsEnabled { get; set; }

    // 如下四個布爾類型的參數主要用於肯定當沒有找到多語言文本時的處理邏輯，默認都爲 True
    bool ReturnGivenTextIfNotFound { get; set; }

    bool WrapGivenTextIfNotFound { get; set; }

    bool HumanizeTextIfNotFound { get; set; }

    bool LogWarnMessageIfNotFound { get; set; }
}

2.2 語言信息

當前應用程序可以支持哪一些語言，取決於用戶在預加載的時候給多語言模塊配置對象分配了哪些語言。經過第 0.1.1 節咱們看到用戶能夠直接經過初始化一個新的 LanguageInfo 對象，將其添加到 Languages 屬性之中。

public class LanguageInfo
{
    /// <summary>
    /// 區域文化代碼名稱
    /// 應該是一個有效的區域文化代碼名稱，更多的能夠經過 CultureInfo 靜態類得到全部文化代碼。
    /// 例如: "en-US" 是北美適用的, "tr-TR" 適用於土耳其。
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 該語言默認應該展現的語言名稱。
    /// 例如: 英語應該展現爲 "English", "zh-Hans" 應該展現爲 "簡體中文"
    /// </summary>
    public string DisplayName { get; set; }

    /// <summary>
    /// 用於展現的圖標 CSS 類名，可選參數
    /// </summary>
    public string Icon { get; set; }

    /// <summary>
    /// 是否爲默認語言
    /// </summary>
    public bool IsDefault { get; set; }

    /// <summary>
    /// 該語言是否被禁用
    /// </summary>
    public bool IsDisabled { get; set; }

    /// <summary>
    /// 語言的展現方式是自左向右仍是自右向左
    /// </summary>
    public bool IsRightToLeft
    {
        get
        {
            try
            {
                return CultureInfo.GetCultureInfo(Name).TextInfo?.IsRightToLeft ?? false;
            }
            catch
            {
                return false;
            }
        }
    }

    public LanguageInfo(string name, string displayName, string icon = null, bool isDefault = false, bool isDisabled = false)
    {
        Name = name;
        DisplayName = displayName;
        Icon = icon;
        IsDefault = isDefault;
        IsDisabled = isDisabled;
    }
}

關於語言的定義仍是至關簡單的，主要參數就是語言的 區域文化代碼 與 展現的名稱，其他的均可以是可選參數。

小提示：

關於當前系統所支持的區域文化代碼，能夠經過執行 CultureInfo.GetCultures(CultureTypes.AllCultures); 獲得。

2.3 語言管理器

Abp 針對語言也提供了一個管理器，接口叫作 ILanguageManager，定義簡單，兩個方法。

public interface ILanguageManager
{
    // 得到當前語言
    LanguageInfo CurrentLanguage { get; }

    // 得到全部語言
    IReadOnlyList<LanguageInfo> GetLanguages();
}

實現也不復雜，它內部的實現就是從一個 ILanguageProvider 拿取有哪一些語言數據。

private readonly ILanguageProvider _languageProvider;

public IReadOnlyList<LanguageInfo> GetLanguages()
{
    return _languageProvider.GetLanguages();
}

// 獲取當前語言，其實就是獲取的 CultureInfo.CurrentUICulture.Name 的信息，而後去查詢語言集合。
private LanguageInfo GetCurrentLanguage()
{
    var languages = _languageProvider.GetLanguages();
    
    // ... 省略了的代碼
    var currentCultureName = CultureInfo.CurrentUICulture.Name;

    var currentLanguage = languages.FirstOrDefault(l => l.Name == currentCultureName);
    if (currentLanguage != null)
    {
        return currentLanguage;
    }
    
    // ... 省略了的代碼
    
    return languages[0];
}

默認實現就是直接讀取以前經過 Configuration 的 Languages 裏面的數據。

在 Abp.Zero 模塊還有兩外一個實現，叫作 ApplicationLanguageProvider ，這個提供者則是從數據庫表 ApplicationLanguage 獲取的這些語言列表數據，而且這些語言信息還與租戶有關，不一樣的租戶他所可以得到到的語言數據也不同。

public IReadOnlyList<LanguageInfo> GetLanguages()
{
    // 能夠看到這裏傳入的當前登陸用戶的租戶 Id，經過這個參數去查詢的語言表數據
    var languageInfos = AsyncHelper.RunSync(() => _applicationLanguageManager.GetLanguagesAsync(AbpSession.TenantId))
        .OrderBy(l => l.DisplayName)
        .Select(l => l.ToLanguageInfo())
        .ToList();

    SetDefaultLanguage(languageInfos);

    return languageInfos;
}

2.4 本地化資源

2.4.1 本地化資源列表

在多語言模塊配置內部使用的是 ILocalizationSourceList 類型的一個 Sources 屬性，該類型其實就是繼承自 IList<ILocalizationSource> 的一個具體實現而已，一個類型爲 ILocalizationSource 的集合，不過其擴展了一個

Extensions 屬性用於存放擴展的多語言數據字段。

2.4.2 本地化資源

其接口定義爲 ILocalizationSource ，Abp 默認爲咱們實現了四種本地化資源的實現。

第一個是空實現，能夠跳過，第二個則是針對資源文件進行讀取的的本地化資源，第三個是基於字典的的本地化資源定義，最後一個是由 Abp Zero 模塊所提供的數據庫版本的多語言資源定義。

首先看一下該接口的定義：

public interface ILocalizationSource
{
    // 本地化資源惟一的名稱
    string Name { get; }

    // 用於初始化本地化資源,在 Abp 框架初始化的時候被調用
    void Initialize(ILocalizationConfiguration configuration, IIocResolver iocResolver);

    // 從當前本地化資源中獲取給定關鍵字的多語言文本項，爲用戶當前語言
    string GetString(string name);

    // 從當前本地化資源中獲取給定關鍵字與區域文化的多語言文本項
    string GetString(string name, CultureInfo culture);

    // 做用同上，只不過不存在會返回 NULL
    string GetStringOrNull(string name, bool tryDefaults = true);

    // 做用同上，只不過不存在會返回 NULL
    string GetStringOrNull(string name, CultureInfo culture, bool tryDefaults = true);

    // 得到當前語言全部的多語言文本項集合
    IReadOnlyList<LocalizedString> GetAllStrings(bool includeDefaults = true);

    // 得到給定區域文化的全部多語言文本項集合
    IReadOnlyList<LocalizedString> GetAllStrings(CultureInfo culture, bool includeDefaults = true);
}

也就能夠這麼來看，咱們有幾套本地化資源，他們經過 Name 來進行標識，若是你須要在本地化管理器獲取某一套本地化資源，那麼你能夠直接經過 Name 來進行定位。而每一套本地化資源，自身都擁有具體的多語言數據，這些多語言數據有可能來自文件也有可能來自數據庫，這取決於你具體的實現。

2.4.3 基於字典的本地化資源

最開始咱們在使用範例當中，經過 DictionaryBasedLocalizationSource 來創建咱們的本地化資源對象。該對象實現了 ILocalizationSource 與 IDictionaryBasedLocalizationSource 接口，內部定義了一個本地化資源字典提供器。

當調用本地化資源的 Initialize() 方法的時候，會使用具體的本地化資源字典提供器來獲取數據，而這個字典提供器能夠爲 XmlFileLocalizationDictionaryProvider、JsonEmbeddedFileLocalizationDictionaryProvider 等。

這些內部字典提供器在初始化的時候，會將自身的數據按照 語言/多語言項 的形式將多語言信息存放在一個字典之中，而這個字典又能夠分爲 XML、JSON 等等等等...

// 內部字典提供器
public interface ILocalizationDictionaryProvider
{
    // 語言/多語言項字典
    IDictionary<string, ILocalizationDictionary> Dictionaries { get; }

    // 本地化資源初始化時被調用
    void Initialize(string sourceName);
}

而這裏的 ILocalizationDictionary 其實就是一個鍵值對，鍵關聯的是多語言項的標識 KEY，例如 "Home"，而 Value 就是具體的展現文本信息了。

而是用字典本地化資源對象獲取數據的時候，其實也就是從其內部的字典提供器來獲取數據。

例如本地化資源有一個 GetString() 方法，它內部擁有一個字典提供器 DictionaryProvider，我要獲取某個 KEY 爲 "Home" 所須要通過的步驟以下。

public ILocalizationDictionaryProvider DictionaryProvider { get; }

public string GetString(string name)
{
    // 獲取當前用戶區域文化，標識爲 "Home" 的展現文本
    return GetString(name, CultureInfo.CurrentUICulture);
}

public string GetString(string name, CultureInfo culture)
{
    // 獲取值
    var value = GetStringOrNull(name, culture);

    // 判斷值爲空的話，根據配置的要求是否拋出異常
    if (value == null)
    {
        return ReturnGivenNameOrThrowException(name, culture);
    }

    return value;
}

// 得到 KEY 關聯的文本
public string GetStringOrNull(string name, CultureInfo culture, bool tryDefaults = true)
{
    var cultureName = culture.Name;
    var dictionaries = DictionaryProvider.Dictionaries;

    // 在這裏就開始從初始化所加載完成的語言字典裏面，獲取具體的多語言項字典
    ILocalizationDictionary originalDictionary;
    if (dictionaries.TryGetValue(cultureName, out originalDictionary))
    {
        // 多語言項字典拿取具體的多語言文本值
        var strOriginal = originalDictionary.GetOrNull(name);
        if (strOriginal != null)
        {
            return strOriginal.Value;
        }
    }

    if (!tryDefaults)
    {
        return null;
    }

    //Try to get from same language dictionary (without country code)
    if (cultureName.Contains("-")) //Example: "tr-TR" (length=5)
    {
        ILocalizationDictionary langDictionary;
        if (dictionaries.TryGetValue(GetBaseCultureName(cultureName), out langDictionary))
        {
            var strLang = langDictionary.GetOrNull(name);
            if (strLang != null)
            {
                return strLang.Value;
            }
        }
    }

    //Try to get from default language
    var defaultDictionary = DictionaryProvider.DefaultDictionary;
    if (defaultDictionary == null)
    {
        return null;
    }

    var strDefault = defaultDictionary.GetOrNull(name);
    if (strDefault == null)
    {
        return null;
    }

    return strDefault.Value;
}

2.3.4 基於數據庫的本地化資源

若是你有集成 Abp.Zero 模塊的話，能夠經過在啓動模塊的預加載方法編寫如下代碼啓用 Zero 的多語言機制。

Configuration.Modules.Zero().LanguageManagement.EnableDbLocalization();

Abp.Zero 針對原有的本地化資源進行了擴展，新增的本地化資源類叫作 MultiTenantLocalizationSource，該類同語言管理器同樣，是一個基於多租戶實現的本地化資源，內部字典的值是從數據庫當中獲取的，其大致邏輯與字典本地化資源同樣，都是內部維護有一個字典提供器。

在經過 EnableDbLocalization() 方法的時候就直接替換掉了 ILanguageProvider 的默認實現，而且在配置的 Sources 源裏面也增長了 MultiTenantLocalizationSource 做爲一個本地化資源。

2.5 本地化資源管理器

扯了這麼多，讓咱們來看一下最爲核心的 ILocalizationManager 接口，若是咱們須要獲取某個數據源的某個 Key 所對應的多語言值確定是要注入這個本地化資源管理器來進行操做的。

public interface ILocalizationManager
{
    // 根據名稱得到本地化數據源
    ILocalizationSource GetSource(string name);

    // 獲取全部的本地化數據源
    IReadOnlyList<ILocalizationSource> GetAllSources();
}

這裏的數據源標識的就是一個命名空間的做用，好比我在 A 模塊當中有一個 Key 爲 "Home" 的多語言項，在 B 模塊也有一個 Key 爲 "Home" 的多語言項，這個時候就能夠用數據源標識來區分這兩個 "Home" 。

本地化資源管理器經過在初始化的時候調用其 Initialize() 來初始化全部被注入的本地化資源，最後並將其放在一個字典之中，以便後續使用。

private readonly IDictionary<string, ILocalizationSource> _sources;

foreach (var source in _configuration.Sources)
{
    // ... 其餘代碼
    _sources[source.Name] = source;
    source.Initialize(_configuration, _iocResolver);
    
    // ... 其餘代碼
}

3.結語

針對 Abp 的多語言處理本篇文章不太適合做爲入門瞭解，其中大部分知識須要結合 Abp 源碼進行閱讀纔可以加深理解，此文僅做拋磚引玉之用，若有任何意見或建議歡迎你們在評論當中指出。

4.點此跳轉到總目錄

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程