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

posted @ 2016-11-01 11:04 kid1412 阅读(...) 评论(...) 编辑 收藏