• ABP文档


    文档目录

    本节内容:

    简介

    任何应用至少有一种用户界面语言,很多应用有多种,ABP为一个应用提供了一个灵活的本地化系统。

    应用语言

    第一件事就是声明支持哪些语言,这在你的模块的PreInitialize方法里完成,如下所示:

    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"));

    在服务端,你可以注入并使用ILocalizationManager,在客户端,你可以使用javascript Api的abp.localization获取所有可用语言列表和当前语言,famfamfam-flag-england (and tr)是一个CSS类,你可根据需要修改它,然后使用它在UI上显示相关的标志。

    ABP模板使用这种方式来显示一个语言切换组合框给用户,从模板创建并查看源码可以了解更多。

    本地化源

    本地化文本可存储于不同的源里,甚至在同一个应用里可以使用多个源(如果你有多个模块,每个模块可以定义一个独立的本地化源,或一个模块定义多个源),一个本地化源应当实现ILocalizationSource接口,然后它被注册到ABP本地化配置里。

    每个本地化源必须有一个唯一的源名称,如下列出预定义的源类型。

    XML文件

    本地化文本可以存储在XML文件里,XML文件内容类似于如下所示:

    <?xml version="1.0" encoding="utf-8" ?>
    <localizationDictionary culture="en">
      <texts>
        <text name="TaskSystem" value="Task System" />
        <text name="TaskList" value="Task List" />
        <text name="NewTask" value="New Task" />
        <text name="Xtasks" value="{0} tasks" />
        <text name="CompletedTasks" value="Completed tasks" />
        <text name="EmailWelcomeMessage">Hi,
    Welcome to Simple Task System! This is a sample
    email content.</text>
      </texts>
    </localizationDictionary>

    XML文件必须包含编码(utf-8),culture=”en“表明这个XML文件包含英文文本,文本的节点:name属性用来标识一个文本,你可以使用value属性或inner text(如最后一个)来设置本地化文本的值,我们为每个语言创建一个独立的XML文件,如下所示:

     

    SimpleTaskSystem是源名称,SimpleTaskSystem.xml定义当前语言,当一个文本被请求,ABP从当前语言的XML文件里获取文本(使用Thread.CurrentThread查找当前语言),如果文本不存在,它将从默认语言的XML文件里查找。

    注册XML本地化源

    XML文件可存储于文件系统里或嵌入到一个程序集里。

    如果XML文件存储于文件系统,我们可以用如下方式注册一个XML本地化源:

    Configuration.Localization.Sources.Add(
        new DictionaryBasedLocalizationSource(
            "SimpleTaskSystem",
            new XmlFileLocalizationDictionaryProvider(
                HttpContext.Current.Server.MapPath("~/Localization/SimpleTaskSystem")
                )
            )
        );

    这在一个模块的PreInitialize事件里完成(更多信息查看模块系统),ABP从指定文件夹里找到所有XML文件并把它们注册为本地化源。

    如果XML嵌入到一个程序集里,我们应当把所有本地化XML文件标记为嵌入的资源(选择XML文件,打开属性窗口(F4)并把生成操作改成嵌入的资源),然后我们可以用如下的方式注册这个本地化源:

    Configuration.Localization.Sources.Add(
        new DictionaryBasedLocalizationSource(
            "SimpleTaskSystem",
            new XmlEmbeddedFileLocalizationDictionaryProvider(
                Assembly.GetExecutingAssembly(),
                "MyCompany.MyProject.Localization.Sources"
                )
            )
        );

    XmlEmbeddedFileLocalizationDictionaryProvider获取一个程序集包含的xml文件(GetExecutingAssembly直接指向当前程序集) 和xml文件的命名空间(命名空间通过计算:程序集名称+XML文件的目录级次)。

    注意:当给嵌入的XML文件添加后缀时,不要使用.号,如“MySource.tr.xml",应当用短横,如”MySource-tr.xml“,因为当查找资源时.号会引起命名空间的问题。

    JSON文件

    JSON文件可以用来存储一个本地化源的文本,下面是一个JSON本地化文件的示例:

    {
      "culture": "en",
      "texts": {
        "TaskSystem": "Task system",
        "Xtasks": "{0} tasks"
      }
    }

    JSON文件应当编码(utf-8),culture:“en“表明这个JSON文件包含英文文本,我们可以为每个语言创建单独的JSON文件,如下所示:

    MySourceName是源名称,MySourceName.json定义了默认语言,这类似于XML文件。

    注册JSON本地化源

    JSON文件可存储在文件系统里或是嵌入到一个程序集中。

    如果存储在文件系统里,我们可以用以下方式注册它:

    Configuration.Localization.Sources.Add(
        new DictionaryBasedLocalizationSource(
            "MySourceName",
            new JsonFileLocalizationDictionaryProvider(
                HttpContext.Current.Server.MapPath("~/Localization/MySourceName")
                )
            )
        );

    这在一个模块的PreInitialize事件里完成(更多信息查看模块系统),ABP从指定文件夹里找到所有JSON文件并把它们注册为本地化源。

    如果JSON嵌入到一个程序集里,我们应当把所有本地化JSON文件标记为嵌入的资源(选择JSON文件,打开属性窗口(F4)并把生成操作改成嵌入的资源),然后我们可以用如下的方式注册这个本地化源:

     Configuration.Localization.Sources.Add(
        new DictionaryBasedLocalizationSource(
            "MySourceName",
            new JsonEmbeddedFileLocalizationDictionaryProvider(
                Assembly.GetExecutingAssembly(),
                "MyCompany.MyProject.Localization.Sources"
                )
            )
        ); 

    JsonEmbeddedFileLocalizationDictionaryProvider获取一个程序集包含的JSON文件(GetExecutingAssembly直接指向当前程序集) 和JSON文件的命名空间(命名空间通过计算:程序集名称+JSON文件的目录级次)。

    注意:当给嵌入的JSON文件添加后缀时,不要使用.号,如“MySource.tr.JSON",应当用短横,如”MySource-tr.JSON“,因为当查找资源时.号会引起命名空间的问题。

    资源文件

    本地化文件同样也能存储于.net资源文件里,我们可以为每个语言创建一个资源文件(右击项目,选择”添加项“,然后找到”资源文件“),如下所示:

    MyTexts.resx包含默认的语言文本,MyTexts.tr.resx包含Turkish(土耳其)语言的文本,当我们打开MyTexts.resx文件,我们可以看到所有文本:

    这种情况下,ABP使用.net内置的资源管理器来使用本地化,你应该把这个资源文件配置为一个本地化源:

    Configuration.Localization.Sources.Add(
        new ResourceFileLocalizationSource(
            "MySource",
            MyTexts.ResourceManager
            ));

    这个源的唯一名称是MySource,MyTexts.ResourceManager是一个指向这个资源管理器的引用,将用它获取本地化文本。这个配置在一个模块的PreInitialize事件里完成(更多信息查看模块系统)。

    自定义源

    一个自定义的源可把文本存储于不同的源,例如一个数据库中,你可以直接实现ILocalizationSource接口或更简单地继承于DictionaryBasedLocalizationSource类(json和xml本地化源也使用这个)。  Module zero 就是在使用数据库。

    获取一个本地文本

    在创建一个源并把它注册到ABP本地化系统后,就可以很简单的本地化文本了。

    在服务端

    在服务端,我们可以注入ILocalizationManager并使用它的GetString方法:

    var s1 = _localizationManager.GetString("SimpleTaskSystem", "NewTask");

    GetString方法基于当前线程的UI文化从本地化源里获取字符串,如果没有找到,它退回到默认语言。

    如果都没定义指定字符串,它默认返回人性化指定字符串并用[和]包裹它(而不抛出异常),例如:如果指定文本是“ThisIsMyText”,结果将是“[This is my text]”,这个行为可配置(可在你的模块的PreInitialize里使用Configuration.Localization)。

    为不一直重复获取源名称,你可以先获取源,然后从源里获取一个字符串:

    var source = _localizationManager.GetSource("SimpleTaskSystem");
    var s1 = source.GetString("NewTask"); 

    这将用返回当前语言的文本,同时有几个用来获取不同语言和不同格式化参数的重载。

    如果我们不能注入ILocalizationManager(可能在一个不能使用依赖注入的静态上下文里),我们可以简单地使用LocalizationHelper静态类,但只要有可能,还是注入并使用ILocalizationManager,因为LocalizationHelper是静态的,不好为它写单元测试。

    如果你需要在一个应用服务、Mvc控制器、Razor视图或继承自AbpServiceBase的类里进行本地化,可以快捷地使用L方法。

    在Mvc控制器里

    在Mvc控制器和视图里通常需要本地化文本,这里有一个快捷的方法,如下示例控制器所示:

    public class HomeController : SimpleTaskSystemControllerBase
    {
        public ActionResult Index()
        {
            var helloWorldText = L("HelloWorld");
            return View();
        }
    }

    用L方法本地化一个字符串,当然必须先提供一个源名称,可以在如下所示的SimpleTaskSystemControllerBase里提供: 

    public abstract class SimpleTaskSystemControllerBase : AbpController
    {
        protected SimpleTaskSystemControllerBase()
        {
            LocalizationSourceName = "SimpleTaskSystem";
        }
    }

    注意:它继承自AbpController,因此你可以非常方便地使用L方法本地化文本。

    在Mvc视图里

    同样,L方法也存在于视图中:

    <div>
        <form id="NewTaskForm" role="form">
            <div class="form-group">
                <label for="TaskDescription">@L("TaskDescription")</label>
                <textarea id="TaskDescription" data-bind="value: task.description" class="form-control" rows="3" placeholder="@L("EnterDescriptionHere")" required></textarea>
            </div>
            <div class="form-group">
                <label for="TaskAssignedPerson">@L("AssignTo")</label>
                <select id="TaskAssignedPerson" data-bind="options: people, optionsText: 'name', optionsValue: 'id', value: task.assignedPersonId, optionsCaption: '@L("SelectPerson")'" class="form-control"></select>
            </div>
            <button data-bind="click: saveTask" type="submit" class="btn btn-primary">@L("CreateTheTask")</button>
        </form>
    </div>

    为了能使用它,你应当让你的视图继承自一个指定了源名称的基类:

    public abstract class SimpleTaskSystemWebViewPageBase : SimpleTaskSystemWebViewPageBase<dynamic>
    {
    
    }
    
    public abstract class SimpleTaskSystemWebViewPageBase<TModel> : AbpWebViewPage<TModel>
    {
        protected SimpleTaskSystemWebViewPageBase()
        {
            LocalizationSourceName = "SimpleTaskSystem";
        }
    }

    并在Web.config中配置这个视图基类:

    <pages pageBaseType="SimpleTaskSystem.Web.Views.SimpleTaskSystemWebViewPageBase"

    如果你的解决方案是从ABP模板创建,那么所有这些都已经完成。 

    在javascript里 

    ABP使在javascript代码里本地化文本成为可能,首先,应该在页面里添加动态ABP脚本:

    <script src="/AbpScripts/GetScripts" type="text/javascript"></script>

    在客户端里,ABP会自动为本地化文本生成必要的javascript代码,然后你就可以很容易地使用javascript获取一个本地的文本,如下所示:

    var s1 = abp.localization.localize('NewTask', 'SimpleTaskSystem');

    NewTask是文本名称,SimpleTaskSystem是源名称,为不重复源名称,你可以先得到源然后获取文本:

    var source = abp.localization.getSource('SimpleTaskSystem');
    var s1 = source('NewTask');

    格式化参数

    Localization方法可以接受额外的格式化参数,例如:

    abp.localization.localize('RoleDeleteWarningMessage', 'MySource', 'Admin');
    
    //shortcut if source is got using getSource as shown above
    source('RoleDeleteWarningMessage', 'Admin'); 

    如果有“ RoleDeleteWarningMessage = 'Role {0} will be deleted'”,那么本地化文本将会是“Role Admin will be deleted”。

    默认本地化源

    你可以设置一个默认的本地化源,然后使用abp.localization.localize方法,不用带源名称参数:

    abp.localization.defaultSourceName = 'SimpleTaskSystem';
    var s1 = abp.localization.localize('NewTask');

    defaultSourceName是全局的并且一次只能是一个源名称。

    扩展本地化源

    假设我们使用一个自身包含了本地化源的模块,因为我们可能要改变它的本地化文本、添加新的文本或翻译成另一种语言,所以ABP允许我们扩展一个本地化源,它目前能工作于XML和JSON文件(实质上,任何实现了IDictionaryBasedLocalizationSource接口的本地化源)。

    ABP同样定义了一些本地化源,例如,Abp.Web nuget包定义了名为“AbpWeb”本地化源,它是一个嵌入的XML文件:

    默认(英文)XML文件,像下面所示(只显示前两个文本):

    <?xml version="1.0" encoding="utf-8" ?>
    <localizationDictionary culture="en">
      <texts>
        <text name="InternalServerError" value="An internal error occurred during your request!" />
        <text name="ValidationError" value="Your request is not valid!" />
        ...
      </texts>
    </localizationDictionary>

    这扩展AbpWeb源,我们可以定义XML文件,假设我们只想修改InternalServerError文本,我们可以定义一下如下所示的XML文件:

    <?xml version="1.0" encoding="utf-8" ?>
    <localizationDictionary culture="en">
      <texts>
        <text name="InternalServerError" value="Sorry :( It seems there is a problem. Let us to solve it and please try again later." />
      </texts>
    </localizationDictionary>

    然后在我们模块的PreInitialize方法里注册它:

    Configuration.Localization.Sources.Extensions.Add(
        new LocalizationSourceExtensionInfo("AbpWeb",
            new XmlFileLocalizationDictionaryProvider(
                HttpContext.Current.Server.MapPath("~/Localization/AbpWebExtensions")
                )
            )
        );

    如果想创建嵌入的XML资源文件(查看本地源小节),我们可以使用XmlEmbeddedFileLocalizationDictionaryProvider,ABP重写(合并)基本地化源和我们的XML文件。我们也可以添加新的语言文件。

    注意: 我们可以使用Json文件来扩展XML文件,反之亦然。

    获取语言

    ILanguageManager用来获取一个所有可用语言列表和当前语言。

    最佳实践

    XML文件、JSON文件和资源文件有它们自身的优缺点,我们建议使用XML或JSON文件,不用资源文件,因为:

    • XML/JSon文件更容易编辑、扩展。
    • XML/JSon文件要求在获取本地化文本时提供字符串键,而不像资源文件那样需要编译时的属性,这也可以看成是一个缺点,但它却可以在以后很容易的修改源,甚至可以移动本地化到一个数据库而不用修改或写本地化代码(Module-Zero实现了它,并创建了一个基础数据库,为每个租户提供本地化源,查看文档)。

    如果你使用XML或JSON,建议你不要把文本按名称排序,要按创建时间排序,因为,当某人把它翻译成另一种语言时,他可以很容易地看出哪一个是新添加的。

    kid1412附:英文原文:http://www.aspnetboilerplate.com/Pages/Documents/Localization

  • 相关阅读:
    Git 命令使用小笔记
    一个关于if else容易迷惑的问题
    浏览器与Node环境下的Event Loop
    镜面反射
    Socket通信原理
    Git
    vba工具
    为什么要用prototype
    Oracle 列转换为行, 逗号拼接.
    JS中的phototype
  • 原文地址:https://www.cnblogs.com/kid1412/p/6018005.html
Copyright © 2020-2023  润新知