ABP官方文档翻译 6.3 本地化 / 憋错料

本地化

介绍
应用程序语言
本地化源
- XML文件
  - 注册XML本地化源
- JSON文件
  - 注册JSON本地化源
- 资源文件
- 自定义源
当前语言是如何决定的
- ASP.NET Core
- ASP.NET MVC 5.x
获取一个本地化文本
- 在服务端
  - 在MVC控制器
  - 在MVC视图
- 在Javascript
  - 格式化参数
  - 默认本地化源
扩展本地化源
获取语言
最佳实践

介绍

　　任何应用程序都会包含至少一种语言。许多的应用程序都包含多种语言。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。在客户端，你可以使用abp.Localization javascript API来获取所有可用语言的列表及当前语言。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文件必须是unicode(utf-8)编码。culture="en"声明标示这个XML文件包含英文文本。对于文本节点，name属性用来定义文本。你可以使用value属性或inner text（如最后一个）来设置本地化文本的值。我们为每一个种语言创建一个单独的XML文件，如下所示：

　　SimpleTaskSystem为源名称，SimpleTaskSystem.xml定义了默认的语言。当文本请求的时候，ABP从当前语言的XML文件中（使用Thread.CurrentThread.CurrentUICulture）获取文本。如果它在当前语言中不存在，则从默认语言的XML文件中获取。

注册XML本地化源

　　XML文件可以存储在文件系统或嵌入到程序集中。

　　对于文件系统存储的XMLs，我们可以按如下所示注册一个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"
            )
        )
    );

　　XmlEmbedddFileLocalizationDictionaryProvider获取包含XML文件（GetExecutingAssembly获取当前程序集）和XML文件命名空间（命名空间由程序集名称+XML文件的目录层级组成）的程序集。

　　注意：当给嵌入的XML文件添加语言前缀时，不要使用点符号如‘MySource.tr.mxl‘，应该使用破折号如‘MySource-tr.xml‘，因为点符号会在查找资源时造成命名空间问题。

JSON文件

　　本地化源可以使用JSON文件来存储文本。一个JSON本地化文件的实例如下：

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

　　JSON文件编码应为unicode(utf-8)。culture:"en"声明标示这个JSON文件包含英文文本。我们我每种语言创建一个单独的JSON文件，如下所示：

　　这里，MySourceName为资源名称，MySourceName.json文件定义了默认的语言。它和XML文件相似。

注册JSON本地化源

　　JOSN文件可以存储在文件系统或嵌入到程序集中。

　　如果文件系统存储JSONs，我么可以按如下方式注册JOSN本地化源：

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

　　这些都是在模块的PreInitialize事件中完成（参见模块系统了解更多信息）。ABP在指定目录查找JSON文件并注册为本地化源。

　　对于嵌入JSON文件，我们需要标记本地的所有的XML文件为嵌入的资源（选择JSON文件，打开属性窗口(F4)，改变生成操作为内嵌资源）。然后我们可以按如下所示注册本地化资源：

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

　　JsonEmbedddFileLocalizationDictionaryProvider获取包含XML文件（GetExecutingAssembly获取当前程序集）和XML文件命名空间（命名空间由程序集名称+XML文件的目录层级组成）的程序集。

　　注意：当给嵌入的JOSN文件添加语言前缀时，不要使用点符号如‘MySource.tr.mxl‘，应该使用破折号如‘MySource-tr.xml‘，因为点符号会在查找资源时造成命名空间问题。

资源文件

　　本地化文本也可以存储在.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在数据库中实现资源。

当前语言是如何决定的

ASP.NET Core

　　ASP.NET Core有自己的机制来决定当前语言。Abp.AspNetCore包自动添加ASP.NET Core的UseRequestLocalization中间件来请求管道。它也添加一些特殊的提供者。这里是所有提供者的默认顺序列表，他们决定HTTP请求的当前语言：

QueryStringRequestCultureProvider(ASP.NET Core`s默认提供者)：使用culture&ui-culture URL查询字符串值。示例值：“culturee=es-MX&ui-culture=es-MX”。
AbpUserRequestCultureProvider(ABP的提供者)：如果用户可以通过IAbpSession得知并且之前显示的选择了一个语言(且保存到ISettingManager)，那么就使用用户喜欢的语言。如果用户可以得知但是没有选择任何语言，且.AspNetCore.Culture cookie或header有值，使用这个信息设置用户的语言设置并使用这个值作为当前语言。如果用户不可得知，这个提供者什么都不做。
AbpLocalizationHeaderRequestCultureProvider(ABP的提供者)：使用.AspNetCore.Culture header值。示例值："c=en|uic=en-US"。
CookieRequestCultureProvider(ASP.NET Core的默认提供者)：使用.AspNetCore.Culture cookie值。示例值：“c=en|uic=en-US”。
AbpDefaultRequestCultureProvider(ABP的提供者)：如果语言(名为"Abp.Localization.DefaultLanguageNmae")有一个默认/应用程序/租户设置值，那么使用这个设置值。
AcceptLanguageHeaderRequestCultureProvider(ASP.NET Core的默认提供者)：使用Accept-Language header值。示例值：“tr-TR,tr;q=0.8,en-US;q=0.6,en;q=0.4”。

　　当使用app.UseAbp()方法时，会自动添加UseRequestLocalization中间件。但是建议在认证中间件之后手动添加它(在Startup类的配置方法中)，如果你的应用程序使用认证校验的话。否则，本地化中间件可以知道当前用户来决定最佳的语言。示例用法：

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    app.UseAbp(options =>
    {
        options.UseAbpRequestLocalization = false; //disable automatic adding of request localization
    });

    //...authentication middleware(s)

    app.UseAbpRequestLocalization(); //manually add request localization

    //...other middlewares

    app.UseMvc(routes =>
    {
        //...
    });
}

　　大多数时候，如果你恰当的使用了ABP的本地化系统，那么你不必关心它。参见ASP.NET Core本地户文档来更好的了解它。

ASP.NET MVC 5.x

　　在每一次网络请求时ABP自动决定当前语言，并设置当前线程的culture(和UI culture)。以下是ABP默认如何决定语言的方式：

尝试一个特定header值，默认名为"Abp.Localization.CultureName"。
如果没找打，尝试获取一个特定的cookie值，默认名为"Abp.Localization.CultureName"。
如果没找到，尝试获取默认的culture设置(设置名为"Abp.Localization.DefaultLanguageName"，是定义在Abp.Localization.LocalizationSettingNames.DefaultLanguage里的一个常量，可以使用设置管理器改变这个值)。
如果没找到，尝试获取浏览器默认的语言(HttpContext.Request.UserLanguages)。

　　如果需要，你可以在模块的PreInitialize方法中改变特定的cookie名称(也是header名称)。示例：

Configuration.Modules.AbpWeb().Localization.CookieName = "YourCustomName";

获取一个本地化文本

　　创建一个资源并注册到ABP本地化系统之后，文本就可以很容易的本地化。

在服务端

　　在服务端，我们注入ILocalizationManager并使用GetString方法。

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

　　GetString方法基于当前线程UI culture从本地化源中获取字符串。如果没找到，它便使用默认语言。

　　如果指定的字符串没有定义，那么它人性化的返回指定的字符串并默认使用‘[‘和‘]‘包装（取代抛出异常）。示例：如果给定的文本为"ThisIsMyText"，那么结果将为“[This is my text]”。这个功能是可以配置的（你可以在模块的PreInitialize方法中使用Configuration.Localization改变它）。

　　为了不要重复使用资源名称，你可以先获得资源，然后从资源中获取字符串：

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

　　这个返回当前语言的文本。GetString有重写版本用来在不用的语言中获取文本或通过参数格式化文本。

　　如果我们不能注入ILocalizationManager（例如在静态context中，不能使用依赖注入系统），我们可以简单的使用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

　　在javascript代码中，ABP也可以使用同样的本地化文本。首先，你要在page中添加动态的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‘);

格式化参数

　　本地化方法可以接收其他的格式化参数。示例：

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>

　　然后我们可以在模块的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或JOSN文件而不是资源文件，因为：

XML/JSON文件易于编辑、扩展或port。
当获取本地化文本时， XML/JSON文件需要字符串key而不是编译时的属性如资源文件。这可以认为是一个弱点。但是，以后容易改变源。甚至我们可以将本地化迁移到数据库而不用改变代码（Module-zero实现它创建一个基于数据库和每个租户的本地化源。参见文档）。

　　如果你使用XML或JSON，建议不要按名称排序文本。按创建时间排序。这样，当其他人把它翻译为其他语言时，他可以轻松的看到哪些文本是新增加的。

返回主目录

时间： 2024-10-18 06:57:05

ABP官方文档翻译 6.3 本地化

ABP官方文档翻译 6.3 本地化的相关文章

ABP官方文档翻译 6.4 导航

ABP官方文档翻译 6.1.2 MVC视图

ABP官方文档翻译 10.1 ABP Nuget包

ABP官方文档翻译 7.3 Quartz集成

ABP官方文档翻译 6.2.1 ASP.NET Core集成

ABP官方文档翻译 4.4 授权

ABP官方文档翻译 4.1 应用服务

ABP官方文档翻译 1.2 N层架构

ABP官方文档翻译 3.4 领域服务