本地化

ABP的本地化系统与Microsoft.Extensions.Localization无缝集成,并与AspnetCore的本地化文档兼容. 它添加了一些实用功能和增强功能, 使其更易于在实际开发中应用.

Volo.Abp.Localization Package

启动模板默认已经安装了此nuget包, 所以在大多数情况下, 你不需要手动安装它.

Volo.Abp.Localization是本地化系统的核心包. 使用程序包管理器控制台 (PMC) 将其安装到项目中:

  1. Install-Package Volo.Abp.Localization

然后, 你可以将 AbpLocalizationModule 依赖项添加到模块:

  1. using Volo.Abp.Modularity;
  2. using Volo.Abp.Localization;
  3. namespace MyCompany.MyProject
  4. {
  5. [DependsOn(typeof(AbpLocalizationModule))]
  6. public class MyModule : AbpModule
  7. {
  8. //...
  9. }
  10. }

创建本地化资源

本地化资源用于将相关的本地化字符串组合在一起,并将它们与应用程序的其他本地化字符串分开.通常一个模块会定义自己的本地化资源. 本地化资源就是一个普通的类. 例如:

  1. public class TestResource
  2. {
  3. }

然后应该使用 AbpLocalizationOptions 添加如下所示:

  1. [DependsOn(typeof(AbpLocalizationModule))]
  2. public class MyModule : AbpModule
  3. {
  4. public override void ConfigureServices(ServiceConfigurationContext context)
  5. {
  6. Configure<AbpVirtualFileSystemOptions>(options =>
  7. {
  8. // "YourRootNameSpace" 是项目的根命名空间名字. 如果你的项目的根命名空间名字为空,则无需传递此参数.
  9. options.FileSets.AddEmbedded<MyModule>("YourRootNameSpace");
  10. });
  11. Configure<AbpLocalizationOptions>(options =>
  12. {
  13. options.Resources
  14. .Add<TestResource>("en")
  15. .AddVirtualJson("/Localization/Resources/Test");
  16. });
  17. }
  18. }

在这个例子中;

  • 添加了一个新的本地化资源, 使用”en”(英语)作为默认的本地化.
  • 用JSON文件存储本地化字符串.
  • 使用虚拟文件系统 将JSON文件嵌入到程序集中.

JSON文件位于 “/Localization/Resources/Test” 项目文件夹下, 如下图所示:

localization-resource-json-files

本地化文件内容如下所示:

  1. {
  2. "culture": "en",
  3. "texts": {
  4. "HelloWorld": "Hello World!"
  5. }
  6. }
  • 每个本地化文件都需要定义 culture (文化) 代码 (例如 “en” 或 “en-US”).
  • texts 部分只包含本地化字符串的键值集合 (键也可能有空格).

默认资源

可以将 AbpLocalizationOptions.DefaultResourceType 设置为资源类型,在未指定本地化资源时使用:

  1. Configure<AbpLocalizationOptions>(options =>
  2. {
  3. options.DefaultResourceType = typeof(TestResource);
  4. });

[启动模板]](/zh-Hans/abp/4.3/Startup-Templates/Application) 设置 DefaultResourceType 为应用程序的本地化资源.

请参阅下面的客户端部分获取用例

简短的本地化资源名称

本地化资源也可以在客户端(JavaScript)使用. 因此, 为本地化资源设置一个简短的名称可以更方便的本地化文本. 例如:

  1. [LocalizationResourceName("Test")]
  2. public class TestResource
  3. {
  4. }

请参阅下面的获取本地化资源Test中客户端部分.

继承其他资源

资源可以从其他资源继承,这使得可以在不引用现有资源的情况下重用现有的本地化字符串. 例如:

  1. [InheritResource(typeof(AbpValidationResource))]
  2. public class TestResource
  3. {
  4. }

也可以通过 AbpLocalizationOptions 配置:

  1. services.Configure<AbpLocalizationOptions>(options =>
  2. {
  3. options.Resources
  4. .Add<TestResource>("en") //Define the resource by "en" default culture
  5. .AddVirtualJson("/Localization/Resources/Test") //Add strings from virtual json files
  6. .AddBaseTypes(typeof(AbpValidationResource)); //Inherit from an existing resource
  7. });
  • 资源可以从多个资源继承.
  • 如果新的本地化资源定义了相同的本地化字符串, 那么它会覆盖该字符串
扩展现有资源

继承资源可以创建新的资源, 无需修改现有的资源. 但是在某些情况下, 你可能不想创建新资源,而是直接扩展现有资源. 例如:

  1. services.Configure<AbpLocalizationOptions>(options =>
  2. {
  3. options.Resources
  4. .Get<TestResource>()
  5. .AddVirtualJson("/Localization/Resources/Test/Extensions");
  6. });
  • 如果扩展文件定义了相同的本地化字符串, 那么它会覆盖该字符串.

获取本地化文本

服务器端

在服务端获取本地化文本的用法是非常标准的(它与AspNetCore提供的获取本地化资源方式无缝集成).

在类中简单的用法
  1. public class MyService
  2. {
  3. private readonly IStringLocalizer<TestResource> _localizer;
  4. public MyService(IStringLocalizer<TestResource> localizer)
  5. {
  6. _localizer = localizer;
  7. }
  8. public void Foo()
  9. {
  10. var str = _localizer["HelloWorld"];
  11. }
  12. }
格式参数

格式参数可以在本地化Key参数后传递,如果你的消息是 Hello {0}, welcome!,可以将 {0} 传递给localizer,例如: _localizer["HelloMessage", "John"].

在Razor视图/Page中简单的用法
  1. @inject IHtmlLocalizer<TestResource> Localizer
  2. <h1>@Localizer["HelloWorld"]</h1>

有关在服务器端使用本地化的详细使用方法, 请参阅AspNetCore的本地化文档

客户端

ABP提供了JavaScript服务, 可以在客户端使用相同的本地化文本.

getResource

abp.localization.getResource 函数用于获取本地化资源:

  1. var testResource = abp.localization.getResource('Test');

本地化字符串:

  1. var str = testResource('HelloWorld');

本地化

abp.localization.localize 函数用于获取本地化文本,你可以传递本地化Key和资源名称:

  1. var str = abp.localization.localize('HelloWorld', 'Test');

HelloWorld 是本地化文本的Key, Test 是本地化资源的名称.

如果未指定本地化资源名称,它使用 AbpLocalizationOptions 中定义的默认本地化资源(参见上面的默认资源部分). 例:

  1. var str = abp.localization.localize('HelloWorld'); //uses the default resource
格式参数

如果本地化字符串包含参数, 例如 Hello {0}, welcome!. 你可以将参数传递给本地化方法. 例:

  1. var str1 = abp.localization.getResource('Test')('HelloWelcomeMessage', 'John');
  2. var str2 = abp.localization.localize('HelloWorld', 'Test', 'John');

上面的两个示例都会输出 Hello John, welcome!.

另请参阅