[Abp vNext 源码分析] – 21. 界面与文字的本地化

摘要

ABP vNext 提供了全套的本地化字符串支持，具体用法可以参考官方使用文档。vNext 本身是对 Microsoft 提供的本地化组件进行了实现，通过 JSON 文件提供本地化源，这一点与老 ABP 不太一样，老 ABP 框架是全套自己手撸。vNext 针对服务端和客户端都提供了文字本地化的工具类，这样开发人员可以很快速地开发支持多语言的网站程序。

一、简介

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() 方法内部，可以看到获取本地化字符串的具体逻辑。

1. 首先会从本地化资源定义的 Contributors 中获取本地化字符串。
2. 如果没有找到则尝试从类似的区域文化信息字典中获取，例如 zh-Hans(简体中文) 源没有拿到则考虑从 zh-Hant(繁体中文)获取。
3. 还是没有取得，最后会使用默认的区域文化信息匹配对应的本地化字符串，一般来说该值建议设置为 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; } 

三、总结

• 点击我跳转到总目录