本地化

ABP的本地化系统与Microsoft.Extensions.Localization包无缝集成，并与微软本地化文档兼容。它增加了一些实用功能和增强特性，使其在实际应用场景中更易使用。

安装

此包已默认包含在启动模板中。因此，大多数情况下无需手动安装。

您可以使用ABP CLI将Volo.Abp.Localization包安装到项目中。在需要安装此包的.csproj文件所在目录下执行以下命令：

abp add-package Volo.Abp.Localization

若尚未安装，需先安装ABP CLI。其他安装选项请参阅包详情页面。

随后在模块中添加AbpLocalizationModule依赖：

using Volo.Abp.Modularity;
using Volo.Abp.Localization;

namespace MyCompany.MyProject
{
    [DependsOn(typeof(AbpLocalizationModule))]
    public class MyModule : AbpModule
    {
        //...
    }
}

创建本地化资源

本地化资源用于将相关的本地化字符串分组，并与应用程序中的其他本地化字符串分离。模块通常定义自己的本地化资源。本地化资源是一个普通类，例如：

public class TestResource
{
}

随后通过AbpLocalizationOptions添加该资源，如下所示：

[DependsOn(typeof(AbpLocalizationModule))]
public class MyModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        Configure<AbpVirtualFileSystemOptions>(options =>
        {
            // "YourRootNameSpace"是项目的根命名空间。若根命名空间为空，此处可为空。
            options.FileSets.AddEmbedded<MyModule>("YourRootNameSpace");
        });

        Configure<AbpLocalizationOptions>(options =>
        {
            //定义新的本地化资源（TestResource）
            options.Resources
                .Add<TestResource>("en")
                .AddVirtualJson("/Localization/Resources/Test");
        });
    }
}

此示例中：

添加了以"en"（英语）为默认文化的新本地化资源。
使用JSON文件存储本地化字符串。
通过AbpVirtualFileSystemOptions将JSON文件嵌入程序集（参见虚拟文件系统）。

JSON文件位于项目文件夹"/Localization/Resources/Test"下，如下图所示：

JSON本地化文件内容示例如下：

{
  "culture": "en",
  "texts": {
    "HelloWorld": "Hello World!"
  }
}

每个本地化文件需定义文件的文化代码（如"en"或"en-US"）。
texts部分包含本地化字符串的键值对集合（键可包含空格）。

若缺少culture部分，ABP将忽略（跳过）该JSON文件。

您还可以在本地化文件中使用嵌套或数组结构，例如：

{
  "culture": "en",
  "texts": {
    "HelloWorld": "Hello World!",
    "Hello": {
        "World": "Hello World!"
    },
    "Hi":[
        "Bye": "Bye World!"
        "Hello": "Hello World!"
    ]
  }
}

随后可按如下方式使用：

双下划线(__)用于分隔父键与子键。

var str = L["Hello__World"]; // Hello World!
var str2 = L["Hi__0"]; // Bye World!
var str3 = L["Hi__1"]; // Hello World!

默认资源

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

Configure<AbpLocalizationOptions>(options =>
{
    options.DefaultResourceType = typeof(TestResource);
});

应用程序启动模板将 DefaultResourceType 设置为应用程序的本地化资源。

简化本地化资源名称

本地化资源在客户端（JavaScript）也可用。因此，为本地化资源设置短名称便于使用本地化文本。例如：

[LocalizationResourceName("Test")]
public class TestResource
{
}

参见下文“获取本地化文本/客户端”部分。

继承其他资源

资源可继承自其他资源，从而无需引用现有资源即可重用其本地化字符串。例如：

[InheritResource(typeof(AbpValidationResource))]
public class TestResource
{
}

通过配置AbpLocalizationOptions的替代继承方式：

services.Configure<AbpLocalizationOptions>(options =>
{
    options.Resources
        .Add<TestResource>("en") //以"en"默认文化定义资源
        .AddVirtualJson("/Localization/Resources/Test") //从虚拟JSON文件添加字符串
        .AddBaseTypes(typeof(AbpValidationResource)); //继承现有资源
});

一个资源可继承多个资源。
若新资源定义了相同的本地化字符串，将覆盖原字符串。

扩展现有资源

继承资源会创建新资源而不修改现有资源。某些情况下，您可能希望不创建新资源，而是直接扩展现有资源。例如：

services.Configure<AbpLocalizationOptions>(options =>
{
    options.Resources
        .Get<TestResource>()
        .AddVirtualJson("/Localization/Resources/Test/Extensions");
});

若扩展文件定义了相同的本地化字符串，将覆盖原字符串。

获取本地化文本

获取本地化文本的方式非常标准。

类中最简用法

只需注入IStringLocalizer<TResource>服务并按如下方式使用：

public class MyService : ITransientDependency
{
    private readonly IStringLocalizer<TestResource> _localizer;

    public MyService(IStringLocalizer<TestResource> localizer)
    {
        _localizer = localizer;
    }

    public void Foo()
    {
        var str = _localizer["HelloWorld"];
    }
}

格式化参数

可在本地化键后传递格式化参数。若消息为Hello {0}, welcome!，则可向本地化器传递{0}参数，如_localizer["HelloMessage", "John"]。

有关使用本地化的详细信息，请参阅微软本地化文档。

在Razor视图/页面中使用

在Razor视图/页面中使用IHtmlLocalizer<T>：

@inject IHtmlLocalizer<TestResource> Localizer

<h1>@Localizer["HelloWorld"]</h1>

特殊基类

部分ABP基类提供L属性，以便更轻松地使用本地化器。

示例：在应用服务方法中本地化文本

using System.Threading.Tasks;
using MyProject.Localization;
using Volo.Abp.Application.Services;

namespace MyProject
{
    public class TestAppService : ApplicationService
    {
        public TestAppService()
        {
            LocalizationResource = typeof(MyProjectResource);
        }

        public async Task DoIt()
        {
            var str = L["HelloWorld"];
        }
    }
}

在构造函数中设置 LocalizationResource 后，ApplicationService 类在使用 L 属性时会使用该资源类型，如 DoIt() 方法所示。

在每个应用服务中设置 LocalizationResource 可能繁琐。可创建抽象基应用服务类，在其中设置并让应用服务继承自该基类。使用启动模板创建新项目时已实现此功能。因此，您可直接继承基类并使用 L 属性：

using System.Threading.Tasks;

namespace MyProject
{
    public class TestAppService : MyProjectAppService
    {
        public async Task DoIt()
        {
            var str = L["HelloWorld"];
        }
    }
}

L属性在其他一些基类（如AbpController和AbpPageModel）中也可用。

支持的语言

可通过配置AbpLocalizationOptions的Languages属性添加应用程序支持的语言。模板已设置常见语言，但您可按如下方式添加新语言：

Configure<AbpLocalizationOptions>(options =>
{
    options.Languages.Add(new LanguageInfo("uz", "uz", "乌兹别克语"));
});

客户端

参阅以下文档了解如何在JavaScript端重用相同的本地化文本：

本地化

安装