[Abp vNext 源碼分析] - 21. 界面與文字的本地化

時間  2020-09-27
標籤 abp vnext 源碼 分析 界面 文字 本地化 简体版
原文   原文鏈接

1、簡介

ABP vNext 提供了全套的本地化字符串支持，具體用法能夠參考官方使用文檔。vNext 自己是對 Microsoft 提供的本地化組件進行了實現，經過 JSON 文件提供本地化源，這一點與老 ABP 不太同樣，老 ABP 框架是全套本身手擼。vNext 針對服務端和客戶端都提供了文字本地化的工具類，這樣開發人員能夠很快速地開發支持多語言的網站程序。html

2、源碼分析

本地化涉及的主要模塊有 Volo.Abp.Localization.Abstractions 和 Volo.Abp.Localization，能夠看到 Volo 針對包的結構也逐漸向 Microsoft 的構建方式靠攏。有直接依賴的模塊是 Volo.Abp.VirtualFileSystem，之因此會引用到這個模塊，是由於默認的本地化數據源是經過內嵌 JSON 文件實現的，因此會用到虛擬文件系統讀取數據。json

2.1 本地化的抽象接口

首先打開 Volo.Abp.Localization.Abstractions 項目，它的基本結構以下圖所示，須要注意的核心類型就是 ILocalizableString 接口和它的兩個具體實現 FixedLocalizableString 與 LocalizableString。緩存

這裏的 IAbpStringLocalizerFactoryWithDefaultResourceSupport 接口是爲 AbpStringLocalizerFactoryExtensions 服務的，後面會詳細解釋，主要做用是根據默認資源類型快速建立一個 IStringLocalizer 實例。框架

2.1.1 本地化字符串對象的封裝

能夠看到在該項目內部定義了一個 ILocalizableString 的接口，在 ABP vNext 內部須要用到多語言表示的字符串屬性，都是定義的 ILocalizableString 類型。本質上它是針對 Microsoft 提供的 LocalizedString 進行了一層包裝，這個接口只提供了一個方法 Localize()，具體的簽名見下面的代碼。ide

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 對象，常見於權限定義的地方，在上面的示例代碼中有用到過。ui

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;
}

3、總結

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