0.簡介
如果你所開發的需要走向世界的話，那么肯定需要針對每一個用戶進行不同的本地化處理，有可能你的客戶在日本，需要使用日語作為顯示文本，也有可能你的客戶在美國，需要使用英語作為顯示文本。如果你還是一樣的寫死錯誤信息，或者描述信息，那么就無法做到多語言適配。
Abp 框架本身提供了一套多語言機制來幫助我們實現本地化，基本思路是 Abp 本身維護一個鍵值對集合。只需要將展示給客戶的文字信息處都使用一個語言 Key 來進行填充，當用戶登錄系統之后，會取得當前用戶的區域文化信息進行文本渲染。
0.1 如何使用
我們首先來看一下如何定義一個多語言資源並使用。首先 Abp 自身支持三種類型的本地化資源來源，第一種是 XML 文件，第二種則是 JSON 文件，第三種則是內嵌資源文件，如果這三種都不能滿足你的需求，你可以自行實現 ILocalizationSource 接口來返回多語言資源。
小提示：
Abp Zero 模塊就提供了數據庫持久化存儲多語言資源的功能。
0.1.1 定義應用程序支持的語言
如果你需要為你的應用程序添加不同語言的支持，就必須在你任意模塊的預加載方法當中添加語言來進行配置：
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"));
例如以上代碼，就能夠讓我們的程序擁有針對英語與土耳其語的多語言處理能力。
這里的 famfamfam-flag-england 與 famfamfam-flag-tr 是一個 CSS 類型，是 Abp 為前端展示所封裝的小國旗圖標。
0.1.2 建立多語言資源文件
有了語言之后，Abp 還需要你提供標准的多語言資源文件，這里我們以 自帶的 XML 資源文件為例，其文件名稱為 Abp-zh-Hans.xml ，路徑為 Abp\Localization\Sources\AbpXmlSource。
<?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 資源文件，文件名稱叫做 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 所提供的，他按照以下順序來進行設置。
- QueryStringRequestCultureProvider(ASP .NET Core 默認提供)：該默認提供器使用的是 QueryString 的
culture&ui-culture所提供的區域文化信息來初始化該值，例如：culture=es-MX&ui-culture=es-MX。 - AbpUserRequestCultureProvider (Abp 提供)：該提供器會讀取當前用戶的
IAbpSession信息，並且從ISettingManager中獲取用戶所配置的"Abp.Localization.DefaultLanguageName"屬性，將其作為默認的區域文化信息。 - **AbpLocalizationHeaderRequestCultureProvider ** (Abp 提供)：使用每次請求頭當中的 .AspNetCore.Culture 值作為當前的區域文化信息，例如
c=en|uic=en-US。 - CookieRequestCultureProvider (ASP .NET Core 提供)：使用每次請求的 Cookie 當中 Key 為 .AspNetCore.Culture 值作為當前區域文化信息。
- AbpDefaultRequestCultureProvider (Abp 提供)：如果之前這些提供器都沒有為當前區域文化賦值，則從
ISettingMananger當中取得Abp.Localization.DefaultLanguageName的默認值。 - 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 源碼進行閱讀才能夠加深理解，此文僅作拋磚引玉之用，如有任何意見或建議歡迎大家在評論當中指出。