## 一、簡介 ABP vNext 提供了全套的本地化字串支援，具體用法可以參考[官方使用文件](https://docs.abp.io/en/abp/latest/Localization)。vNext 本身是對 Microsoft 提供的本地化元件進行了實現，通過 JSON 檔案提供本地化源，這一點與老 ABP 不太一樣，老 ABP 框架是全套自己手擼。vNext 針對服務端和客戶端都提供了文字本地化的工具類，這樣開發人員可以很快速地開發支援多語言的網站程式。 ## 二、原始碼分析 本地化涉及的主要模組有 **Volo.Abp.Localization.Abstractions** 和 **Volo.Abp.Localization**，可以看到 Volo 針對包的結構也逐漸向 Microsoft 的構建方式靠攏。有直接依賴的模組是 **Volo.Abp.VirtualFileSystem**，之所以會引用到這個模組，是因為預設的本地化資料來源是通過內嵌 JSON 檔案實現的，所以會用到虛擬檔案系統讀取資料。 ### 2.1 本地化的抽象介面 首先開啟 **Volo.Abp.Localization.Abstractions** 專案，它的基本結構如下圖所示，需要注意的核心型別就是 `ILocalizableString` 介面和它的兩個具體實現 `FixedLocalizableString` 與 `LocalizableString`。 這裡的 `IAbpStringLocalizerFactoryWithDefaultResourceSupport` 介面是為 `AbpStringLocalizerFactoryExtensions` 服務的，後面會詳細解釋，主要作用是根據預設資源型別快速建立一個 `IStringLocalizer` 例項。  #### 2.1.1 本地化字串物件的封裝 可以看到在該專案內部定義了一個 `ILocalizableString` 的介面，在 ABP vNext 內部需要用到多語言表示的字串屬性，都是定義的 `ILocalizableString` 型別。本質上它是針對 Microsoft 提供的 `LocalizedString` 進行了一層包裝，這個介面只提供了一個方法 `Localize()`，具體的簽名見下面的程式碼。 ```csharp public interface ILocalizableString { LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory); } ``` 在 ABP vNext 框架當中，擁有兩個實現，分別是 `LocalizableString` 和 `FixedLocalizableString`，後者用於建立固定字串的顯示。例如 ABP vNext 自帶的許可權系統，針對許可權名稱和描述必須傳遞 `ILocalizableString` 型別的值，但是開發人員暫時沒有提供對應的本地化翻譯，這個時候就可以使用 `FixedLocalizableString` 傳遞固定字串。 實現也是很簡單，在呼叫了 `Localize()` 方法之後，會根據建構函式的 **Value** 建立一個新的 `LocalizedString` 物件。 ```csharp public class FixedLocalizableString : ILocalizableString { public string Value { get; } public FixedLocalizableString(string value) { Value = value; } public LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory) { return new LocalizedString(Value, Value); } } ``` 用法舉例: ```csharp public class DataDictionaryDefinitionPermissionProvider : PermissionDefinitionProvider { public override void Define(IPermissionDefinitionContext context) { var dataDictionaryGroup = context.AddGroup(DataDictionaryPermissions.GroupName, L("Permission:DataDictionary")); var dataDictionary = dataDictionaryGroup.AddPermission(DataDictionaryPermissions.DataDictionary.Default, L("Permission:DataDictionary")); dataDictionary.AddChild(DataDictionaryPermissions.DataDictionary.Create, L("Permission:Create")); dataDictionary.AddChild(DataDictionaryPermissions.DataDictionary.Update, L("Permission:Edit")); dataDictionary.AddChild(DataDictionaryPermissions.DataDictionary.Delete, L("Permission:Delete")); // 這裡使用了 FixedLocalizableString 提供本地化字串。 dataDictionary.AddChild(DataDictionaryPermissions.DataDictionary.Management, new FixedLocalizableString("字典管理")); } private static LocalizableString L(string name) { return LocalizableString.Create(name); } } ``` 另一個 `LocalizableString` 就是正常通過 `IStringLocalizerFactory` 獲取的本地化字串物件。 ```csharp public class LocalizableString : ILocalizableString { [CanBeNull] public Type ResourceType { get; } [NotNull] public string Name { get; } public LocalizableString(Type resourceType, [NotNull] string name) { Name = Check.NotNullOrEmpty(name, nameof(name)); ResourceType = resourceType; } public LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory) { return stringLocalizerFactory.Create(ResourceType)[Name]; } public static LocalizableString Create([NotNull] string name) { return new LocalizableString(typeof(TResource), name); } } ``` 在型別裡面定義了一個靜態方法，用於目標型別與 KEY 的 `LocalizableString` 物件，常見於許可權定義的地方，在上面的示例程式碼中有用到過。 #### 2.1.2 本地化資源型別的別名 TODO ### 2.2 本地化的基礎設施 下文指代的基礎設施是指 ABP vNext 為了優雅地實現 Microsoft 本地化介面所構建的一系列元件，ABP vNext 的大部分元件都是基於 Microsoft 提供的抽象體系，也是為了更好地相容。 #### 2.2.1 模組的啟動 具體的實現模組邏輯也不復雜，首先替換了預設的本地化資源容器工廠。接著往 ABP 的虛擬檔案系統添加了當前模組，以便後續訪問對應的 JSON 檔案，最後往本地化的相關配置項添加了兩個本地化資源。 ```csharp public class AbpLocalizationModule : AbpModule { public override void ConfigureServices(ServiceConfigurationContext context) { AbpStringLocalizerFactory.Replace(context.Services); Configure(options => { options.FileSets.AddEmbedded("Volo.Abp", "Volo/Abp"); }); Configure(options => { options .Resources .Add("en"); options .Resources .Add("en") .AddVirtualJson("/Localization/Resources/AbpLocalization"); }); } } ``` #### 2.2.2 本地化的配置 `AbpLocalizationOptions` 內部定義了本地化系統的相關引數，主要由資源集合(`Resources`)、預設資源(`DefaultResourceType`)、全域性的本地化資料來源提供者(`GlobalContributors`)、支援的語言(`Languages`)。 > **注意:** > > 當進行本地化操作時，沒有指定資源型別的時候會使用預設資源型別。 ```csharp public class AbpLocalizationOptions { public LocalizationResourceDictionary Resources { get; } public Type DefaultResourceType { get; set; } public ITypeList GlobalContributors { get; } public List Languages { get; } public Dictionary> LanguagesMap { get; } public Dictionary> LanguageFilesMap { get; } public AbpLocalizationOptions() { Resources = new LocalizationResourceDictionary(); GlobalContributors = new TypeList(); Languages = new List(); LanguagesMap = new Dictionary>(); LanguageFilesMap = new Dictionary>(); } } ``` 從上述程式碼我們可以知道，要讓本地化系統正常工作，我們會接觸到下面這幾個型別 `LocalizationResourceDictionary`、`LocalizationResource`、`ILocalizationResourceContributor`、`LanguageInfo`。 #### 2.2.3 本地化資源的定義 在使用本地化系統的時候，ABP vNext 文件首先會讓我們定義一個型別，並在模組的 `ConfigureService()` 週期，通過配置項新增到本地化系統當中，就像這樣。 ```csharp Configure(options => { options.Resources .Add("en") .AddVirtualJson("/Localization/Resources"); }); ``` 這裡可以看到，ABP vNext 實現了一套流暢方法(Fluent Method)，通過這一系列的操作，我們會生成一個 `LocalizationResource` 例項，新增到配置系統當中，以便後續進行使用。 這裡的 `Add()` 方法是由 `LocalizationResourceDictionary` 提供的，它本質上就是一個字典，只不過由 ABP vNext 封裝了一些自定義的方法，方便新增字典項資料。可以看到它的實現也很簡單，首先判斷字典是否存在對應的 Key，如果不存在就使用資源型別和區域文化資訊構造一個新的 `LocalizationResource` 物件，並將其新增到字典當中。 ```csharp public class LocalizationResourceDictionary : Dictionary { public LocalizationResource Add([CanBeNull] string defaultCultureName = null) { return Add(typeof(TResouce), defaultCultureName); } public LocalizationResource Add(Type resourceType, [CanBeNull] string defaultCultureName = null) { if (ContainsKey(resourceType)) { throw new AbpException("This resource is already added before: " + resourceType.AssemblyQualifiedName); } return this[resourceType] = new LocalizationResource(resourceType, defaultCultureName); } // ... 其他程式碼。 } ``` 轉到 `LocalizationResouce` 的定義，內部儲存了具體的資源型別、資源名稱、當前資源預設的區域文化資訊、本地化資料來源提供者(與全域性的不同，這裡僅作用於某個具體本地化資源)、繼承的基類資源型別集合。 資源型別和資源名稱用於區分不同的本地化資源。預設區域文化資訊代表當前資源，當獲取指定語言的本地化字串失敗時，會讀取預設的區域文化資訊對應的本地化字串。 這裡的 `BaseResouceTypes` 是為了複用其他資源的本地化字串，例如你定義了一個 `AppleResouceType`，但是你想要獲取 `FruitResouceType` 對應的字串，那麼就需要往這個集合新增需要服用的資源型別。ABP vNext 為 `LocalizationResource` 提供了一個擴充套件方法 `AddBaseTypes()` 便於在模組配置時新增需要複用的型別。除此之外 ABP vNext 也提供了特性支援，跟模組定義一樣，在類定義上面新增 `InheritResourceAttribute` 特性，傳入需要複用的型別定義即可。 ```csharp [InheritResource( typeof(LocalizationTestValidationResource), typeof(LocalizationTestCountryNamesResource) )] public sealed class LocalizationTestResource { } ``` 可以看到在下述程式碼當中，ABP vNext 會掃描當前 `ResouceType` 的特性，並將其定義的複用型別新增到基類集合當中。 ```csharp public class LocalizationResource { [NotNull] public Type ResourceType { get; } [NotNull] public string ResourceName => LocalizationResourceNameAttribute.GetName(ResourceType); [CanBeNull] public string DefaultCultureName { get; set; } [NotNull] public LocalizationResourceContributorList Contributors { get; } [NotNull] public List BaseResourceTypes { get; } public LocalizationResource( [NotNull] Type resourceType, [CanBeNull] string defaultCultureName = null, [CanBeNull] ILocalizationResourceContributor initialContributor = null) { ResourceType = Check.NotNull(resourceType, nameof(resourceType)); DefaultCultureName = defaultCultureName; BaseResourceTypes = new List(); Contributors = new LocalizationResourceContributorList(); if (initialContributor != null) { Contributors.Add(initialContributor); } AddBaseResourceTypes(); } protected virtual void AddBaseResourceTypes() { var descriptors = ResourceType .GetCustomAttributes(true) .OfType(); foreach (var descriptor in descriptors) { foreach (var baseResourceType in descriptor.GetInheritedResourceTypes()) { BaseResourceTypes.AddIfNotContains(baseResourceType); } } } } ``` 當資源型別(**Resource Type**) 定義好之後，通過上面的一番操作，就能夠得到一個 `LocalizationResource` 例項，並將其新增到了 `AbpLocalizationOptions` 內的 `LocalizationResourceDictionary` 物件。開發人員定義了多少個本地化資源型別，就會往這個字典新增多少個 `LocaliztaionResource` 例項。 #### 2.2.4 本地化的資料來源 不論是配置項還是某個本地化資源定義類，都會儲存一組 `Contributor` 。轉到對應的介面定義，這個介面定義了三個公開方法，分別用於初始化(`Initialize()`)、獲取某個具體的本地化字串(`LocalizedString()`)、為指定的字典填充本地化資源資料(`Fill()`)。 ```csharp public interface ILocalizationResourceContributor { void Initialize(LocalizationResourceInitializationContext context); LocalizedString GetOrNull(string cultureName, string name); void Fill(string cultureName, Dictionary dictionary); } ``` 所有的資料來源都是由各個 `Contributor` 提供的，這裡以 `VirtualFileLocalizationResourceContributorBase` 為例，在內部通過虛擬檔案系統獲取到了檔案資料，通過檔案資料構造一系列的字典。這裡的 **字典有兩層**，第一層的 Key 是區域文化資訊，Value 是對應區域文化資訊的本地化字串字典。第二層的 Key 是本地化字串的標識，Value 就是具體的 `LocalizedString` 例項。 ```csharp public abstract class VirtualFileLocalizationResourceContributorBase : ILocalizationResourceContributor { // ... 其他程式碼 public void Initialize(LocalizationResourceInitializationContext context) { _virtualFileProvider = context.ServiceProvider.GetRequiredService(); } public LocalizedString GetOrNull(string cultureName, string name) { return GetDictionaries().GetOrDefault(cultureName)?.GetOrNull(name); } public void Fill(string cultureName, Dictionary dictionary) { GetDictionaries().GetOrDefault(cultureName)?.Fill(dictionary); } private Dictionary GetDictionaries() { // ... 獲取本地化資源的字典，這裡的字典按區域文化進行分組。 } private Dictionary CreateDictionaries() { var dictionaries = new Dictionary(); foreach (var file in _virtualFileProvider.GetDirectoryContents(_virtualPath)) { // ... 其他程式碼。 // 根據檔案建立某個區域文化的具體的資料來源字典。 var dictionary = CreateDictionaryFromFile(file); if (dictionaries.ContainsKey(dictionary.CultureName)) { throw new AbpException($"{file.GetVirtualOrPhysicalPathOrNull()} dictionary has a culture name '{dictionary.CultureName}' which is already defined!"); } dictionaries[dictionary.CultureName] = dictionary; } return dictionaries; } protected abstract bool CanParseFile(IFileInfo file); protected virtual ILocalizationDictionary CreateDictionaryFromFile(IFileInfo file) { using (var stream = file.CreateReadStream()) { return CreateDictionaryFromFileContent(Utf8Helper.ReadStringFromStream(stream)); } } protected abstract ILocalizationDictionary CreateDictionaryFromFileContent(string fileContent); } ``` #### 2.2.5 本地化資源字典 具體儲存本地化字串標識和展示文字的物件是 `ILocalizationDictionary`，它的具體實現是 `StaticLocalizationDictionary`，在其內部有一個 `Dictionary` 字典，這個字典就對應的 JSON 檔案當中的本地化資料了。 ```json { "culture": "zh-Hans", "texts": { "DisplayName:Abp.Localization.DefaultLanguage": "預設語言", "Description:Abp.Localization.DefaultLanguage": "應用程式的預設語言." } } ``` 對應的字典形式就是內部字典的 `KEY:Value`。 ```csharp public class StaticLocalizationDictionary : ILocalizationDictionary { public string CultureName { get; } protected Dictionary Dictionary { get; } public StaticLocalizationDictionary(string cultureName, Dictionary dictionary) { CultureName = cultureName; Dictionary = dictionary; } public virtual LocalizedString GetOrNull(string name) { return Dictionary.GetOrDefault(name); } public void Fill(Dictionary dictionary) { foreach (var item in Dictionary) { dictionary[item.Key] = item.Value; } } } ``` 當最外層的 Contributor 獲取文字的時候，實際是結合區域文化資訊(Culture Name) 定義到對應的本地化資源字典，再通過 Name 獲取資源字典內部對應的 `LocalizedString` 物件。 ### 2.3 同 Microsoft 本地化整合 2.2 節講完了 ABP vNext 實現的基礎設施，結合某個資源型別附帶的 Contributor 組就能夠獲取到具體的本地化字串資料，在本節主要講解 ABP vNext 同 Microsoft 的整合。 #### 2.3.1 IStringLocalizer 工廠 在 `AbpLocalizationModule` 模組中，第一句就是替換了預設的 String Localizer 工廠，並注入了 `ResourceManagerStringLocalizerFactory` 型別，這個型別主要用於後續的預設行為。 ```csharp internal static void Replace(IServiceCollection services) { services.Replace(ServiceDescriptor.Singleton()); services.AddSingleton(); } ``` 在 Microsoft 提供的 `IStringLocalizerFactory` 介面中，只定義了兩個建立 `IStringLocalizer` 的方法。 ```csharp public interface IStringLocalizerFactory { IStringLocalizer Create(Type resourceSource); IStringLocalizer Create(string baseName, string location); } ``` 第二個方法 ABP 是直接呼叫的預設工廠(`ResouceManagerStringLocalizerFactory`) 提供的方法，而且還加了個 TODO 註明不知道什麼時候會被呼叫。 ```csharp public virtual IStringLocalizer Create(string baseName, string location) { //TODO: Investigate when this is called? return InnerFactory.Create(baseName, location); } ``` 這裡我們著重關注第一個方法，ABP 主要實現的也是第一個方法，它會根據傳入的 `resourceSource` 引數從快取當中獲取(不存在則構造)對應的 `IStringLocalizer` 。如果在 ABP 提供的資源集合當中，沒有查詢到對應的 Type，則直接呼叫預設工廠返回 `IStringLocalizer`。如果存在則會以 Type 作為 Key，`StringLocalizerCacheItem`(就是 `LocalizationResource` 的馬甲) 作為 Value，從快取拿，沒拿到就構建一個新的並加入到快取中。 ```csharp public virtual IStringLocalizer Create(Type resourceType) { var resource = AbpLocalizationOptions.Resources.GetOrDefault(resourceType); if (resource == null) { return InnerFactory.Create(resourceType); } if (LocalizerCache.TryGetValue(resourceType, out var cacheItem)) { return cacheItem.Localizer; } lock (LocalizerCache) { return LocalizerCache.GetOrAdd( resourceType, _ => CreateStringLocalizerCacheItem(resource) ).Localizer; } } private StringLocalizerCacheItem CreateStringLocalizerCacheItem(LocalizationResource resource) { // 構造時會將全域性配置的 Contributor 新增到對應的組。 foreach (var globalContributor in AbpLocalizationOptions.GlobalContributors) { resource.Contributors.Add((ILocalizationResourceContributor) Activator.CreateInstance(globalContributor)); } using (var scope = ServiceProvider.CreateScope()) { var context = new LocalizationResourceInitializationContext(resource, scope.ServiceProvider); // 呼叫各個 Contributor 的初始化方法，進行初始化操作。 foreach (var contributor in resource.Contributors) { contributor.Initialize(context); } } return new StringLocalizerCacheItem( new AbpDictionaryBasedStringLocalizer( resource, resource.BaseResourceTypes.Select(Create).ToList() ) ); } ``` #### 2.3.2 IStringLocalizer ABP 針對 `IStringLocalizer` 的預設實現是 `AbpDictionaryBasedStringLocalizer`，`IStringLocalizer` 主要包含兩個索引器和一個 `GetAllStrings()` 方法。 索引器本身直接就呼叫的 `GetLocalizedString()` 與 `GetLocalizedStringFormatted()` 方法。後者用於處理格式化的引數，內部就是利用的 `string.Format()` 方法替換佔位符的內容。 ```csharp public class AbpDictionaryBasedStringLocalizer : IStringLocalizer, IStringLocalizerSupportsInheritance { // ... 其他程式碼 public virtual LocalizedString this[string name] => GetLocalizedString(name); public virtual LocalizedString this[string name, params object[] arguments] => GetLocalizedStringFormatted(name, arguments); // ... 其他程式碼 protected virtual LocalizedString GetLocalizedString(string name) { return GetLocalizedString(name, CultureInfo.CurrentUICulture.Name); } protected virtual LocalizedString GetLocalizedString(string name, string cultureName) { var value = GetLocalizedStringOrNull(name, cultureName); // 如果沒有從當前容器取得對應的本地化字串，就從複用的基類中獲取。 if (value == null) { foreach (var baseLocalizer in BaseLocalizers) { using (CultureHelper.Use(CultureInfo.GetCultureInfo(cultureName))) { var baseLocalizedString = baseLocalizer[name]; if (baseLocalizedString != null && !baseLocalizedString.ResourceNotFound) { return baseLocalizedString; } } } return new LocalizedString(name, name, resourceNotFound: true); } return value; } } ``` 轉到 `GetLocalizedStringOrNull()` 方法內部，可以看到獲取本地化字串的具體邏輯。 1. 首先會從本地化資源定義的 Contributors 中獲取本地化字串。 2. 如果沒有找到則嘗試從類似的區域文化資訊字典中獲取，例如 zh-Hans(簡體中文) 源沒有拿到則考慮從 zh-Hant(繁體中文)獲取。 3. 還是沒有取得，最後會使用預設的區域文化資訊匹配對應的本地化字串，一般來說該值建議設定為 `en`。 ```csharp protected virtual LocalizedString GetLocalizedStringOrNull(string name, string cultureName, bool tryDefaults = true) { //Try to get from original dictionary (with country code) var strOriginal = Resource.Contributors.GetOrNull(cultureName, name); if (strOriginal != null) { return strOriginal; } if (!tryDefaults) { return null; } //Try to get from same language dictionary (without country code) if (cultureName.Contains("-")) //Example: "tr-TR" (length=5) { var strLang = Resource.Contributors.GetOrNull(CultureHelper.GetBaseCultureName(cultureName), name); if (strLang != null) { return strLang; } } //Try to get from default language if (!Resource.DefaultCultureName.IsNullOrEmpty()) { var strDefault = Resource.Contributors.GetOrNull(Resource.DefaultCultureName, name); if (strDefault != null) { return strDefault; } } //Not found return null; } ``` ## 三、總結 - [點選我跳轉到總目錄](https://www.cnblogs.com/myzony/p/1072250