一、簡介
ABP vNext 提供了全套的本地化字串支援,具體用法可以參考官方使用文件。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()
,具體的簽名見下面的程式碼。
public interface ILocalizableString
{
LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory);
}
在 ABP vNext 框架當中,擁有兩個實現,分別是 LocalizableString
和 FixedLocalizableString
,後者用於建立固定字串的顯示。例如 ABP vNext 自帶的許可權系統,針對許可權名稱和描述必須傳遞 ILocalizableString
型別的值,但是開發人員暫時沒有提供對應的本地化翻譯,這個時候就可以使用 FixedLocalizableString
傳遞固定字串。
實現也是很簡單,在呼叫了 Localize()
方法之後,會根據建構函式的 Value 建立一個新的 LocalizedString
物件。
public class FixedLocalizableString : ILocalizableString
{
public string Value { get; }
public FixedLocalizableString(string value)
{
Value = value;
}
public LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory)
{
return new LocalizedString(Value, Value);
}
}
用法舉例:
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<DataDictionaryResource>(name);
}
}
另一個 LocalizableString
就是正常通過 IStringLocalizerFactory
獲取的本地化字串物件。
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<TResource>([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 檔案,最後往本地化的相關配置項新增了兩個本地化資源。
public class AbpLocalizationModule : AbpModule
{
public override void ConfigureServices(ServiceConfigurationContext context)
{
AbpStringLocalizerFactory.Replace(context.Services);
Configure<AbpVirtualFileSystemOptions>(options =>
{
options.FileSets.AddEmbedded<AbpLocalizationModule>("Volo.Abp", "Volo/Abp");
});
Configure<AbpLocalizationOptions>(options =>
{
options
.Resources
.Add<DefaultResource>("en");
options
.Resources
.Add<AbpLocalizationResource>("en")
.AddVirtualJson("/Localization/Resources/AbpLocalization");
});
}
}
2.2.2 本地化的配置
AbpLocalizationOptions
內部定義了本地化系統的相關引數,主要由資源集合(Resources
)、預設資源(DefaultResourceType
)、全域性的本地化資料來源提供者(GlobalContributors
)、支援的語言(Languages
)。
注意:
當進行本地化操作時,沒有指定資源型別的時候會使用預設資源型別。
public class AbpLocalizationOptions
{
public LocalizationResourceDictionary Resources { get; }
public Type DefaultResourceType { get; set; }
public ITypeList<ILocalizationResourceContributor> GlobalContributors { get; }
public List<LanguageInfo> Languages { get; }
public Dictionary<string, List<NameValue>> LanguagesMap { get; }
public Dictionary<string, List<NameValue>> LanguageFilesMap { get; }
public AbpLocalizationOptions()
{
Resources = new LocalizationResourceDictionary();
GlobalContributors = new TypeList<ILocalizationResourceContributor>();
Languages = new List<LanguageInfo>();
LanguagesMap = new Dictionary<string, List<NameValue>>();
LanguageFilesMap = new Dictionary<string, List<NameValue>>();
}
}
從上述程式碼我們可以知道,要讓本地化系統正常工作,我們會接觸到下面這幾個型別 LocalizationResourceDictionary
、LocalizationResource
、ILocalizationResourceContributor
、LanguageInfo
。
2.2.3 本地化資源的定義
在使用本地化系統的時候,ABP vNext 文件首先會讓我們定義一個型別,並在模組的 ConfigureService()
週期,通過配置項新增到本地化系統當中,就像這樣。
Configure<AbpLocalizationOptions>(options =>
{
options.Resources
.Add<DataDictionaryResource>("en")
.AddVirtualJson("/Localization/Resources");
});
這裡可以看到,ABP vNext 實現了一套流暢方法(Fluent Method),通過這一系列的操作,我們會生成一個 LocalizationResource
例項,新增到配置系統當中,以便後續進行使用。
這裡的 Add()
方法是由 LocalizationResourceDictionary
提供的,它本質上就是一個字典,只不過由 ABP vNext 封裝了一些自定義的方法,方便新增字典項資料。可以看到它的實現也很簡單,首先判斷字典是否存在對應的 Key,如果不存在就使用資源型別和區域文化資訊構造一個新的 LocalizationResource
物件,並將其新增到字典當中。
public class LocalizationResourceDictionary : Dictionary<Type, LocalizationResource>
{
public LocalizationResource Add<TResouce>([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
特性,傳入需要複用的型別定義即可。
[InheritResource(
typeof(LocalizationTestValidationResource),
typeof(LocalizationTestCountryNamesResource)
)]
public sealed class LocalizationTestResource
{
}
可以看到在下述程式碼當中,ABP vNext 會掃描當前 ResouceType
的特性,並將其定義的複用型別新增到基類集合當中。
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<Type> 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<Type>();
Contributors = new LocalizationResourceContributorList();
if (initialContributor != null)
{
Contributors.Add(initialContributor);
}
AddBaseResourceTypes();
}
protected virtual void AddBaseResourceTypes()
{
var descriptors = ResourceType
.GetCustomAttributes(true)
.OfType<IInheritedResourceTypesProvider>();
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()
)。
public interface ILocalizationResourceContributor
{
void Initialize(LocalizationResourceInitializationContext context);
LocalizedString GetOrNull(string cultureName, string name);
void Fill(string cultureName, Dictionary<string, LocalizedString> dictionary);
}
所有的資料來源都是由各個 Contributor
提供的,這裡以 VirtualFileLocalizationResourceContributorBase
為例,在內部通過虛擬檔案系統獲取到了檔案資料,通過檔案資料構造一系列的字典。這裡的 字典有兩層,第一層的 Key 是區域文化資訊,Value 是對應區域文化資訊的本地化字串字典。第二層的 Key 是本地化字串的標識,Value 就是具體的 LocalizedString
例項。
public abstract class VirtualFileLocalizationResourceContributorBase : ILocalizationResourceContributor
{
// ... 其他程式碼
public void Initialize(LocalizationResourceInitializationContext context)
{
_virtualFileProvider = context.ServiceProvider.GetRequiredService<IVirtualFileProvider>();
}
public LocalizedString GetOrNull(string cultureName, string name)
{
return GetDictionaries().GetOrDefault(cultureName)?.GetOrNull(name);
}
public void Fill(string cultureName, Dictionary<string, LocalizedString> dictionary)
{
GetDictionaries().GetOrDefault(cultureName)?.Fill(dictionary);
}
private Dictionary<string, ILocalizationDictionary> GetDictionaries()
{
// ... 獲取本地化資源的字典,這裡的字典按區域文化進行分組。
}
private Dictionary<string, ILocalizationDictionary> CreateDictionaries()
{
var dictionaries = new Dictionary<string, ILocalizationDictionary>();
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<string, LocalizedString>
字典,這個字典就對應的 JSON 檔案當中的本地化資料了。
{
"culture": "zh-Hans",
"texts": {
"DisplayName:Abp.Localization.DefaultLanguage": "預設語言",
"Description:Abp.Localization.DefaultLanguage": "應用程式的預設語言."
}
}
對應的字典形式就是內部字典的 KEY:Value
。
public class StaticLocalizationDictionary : ILocalizationDictionary
{
public string CultureName { get; }
protected Dictionary<string, LocalizedString> Dictionary { get; }
public StaticLocalizationDictionary(string cultureName, Dictionary<string, LocalizedString> dictionary)
{
CultureName = cultureName;
Dictionary = dictionary;
}
public virtual LocalizedString GetOrNull(string name)
{
return Dictionary.GetOrDefault(name);
}
public void Fill(Dictionary<string, LocalizedString> 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
型別,這個型別主要用於後續的預設行為。
internal static void Replace(IServiceCollection services)
{
services.Replace(ServiceDescriptor.Singleton<IStringLocalizerFactory, AbpStringLocalizerFactory>());
services.AddSingleton<ResourceManagerStringLocalizerFactory>();
}
在 Microsoft 提供的 IStringLocalizerFactory
介面中,只定義了兩個建立 IStringLocalizer
的方法。
public interface IStringLocalizerFactory
{
IStringLocalizer Create(Type resourceSource);
IStringLocalizer Create(string baseName, string location);
}
第二個方法 ABP 是直接呼叫的預設工廠(ResouceManagerStringLocalizerFactory
) 提供的方法,而且還加了個 TODO 註明不知道什麼時候會被呼叫。
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,從快取拿,沒拿到就構建一個新的並加入到快取中。
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()
方法替換佔位符的內容。
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()
方法內部,可以看到獲取本地化字串的具體邏輯。
- 首先會從本地化資源定義的 Contributors 中獲取本地化字串。
- 如果沒有找到則嘗試從類似的區域文化資訊字典中獲取,例如 zh-Hans(簡體中文) 源沒有拿到則考慮從 zh-Hant(繁體中文)獲取。
- 還是沒有取得,最後會使用預設的區域文化資訊匹配對應的本地化字串,一般來說該值建議設定為
en
。
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;
}