系列导航及源代码

需求

在开发一些需要支持多种语言的应用程序时,我们需要根据切换的语言来对应展示一些静态的字符串字段,在本文中我们暂时不去讨论如何结合前端一起来实现根据切换当前应用程序的Culture来实现字符串的自动切换和日期时间的切换,只通过一个简单的例子来展示如何在.NET Web API项目中实现多语言字符串的功能。

目标

作为演示,实现支持英文和中文的本地化语言。

原理与思路

实现静态字符串的本地化切换功能实际很简单,我们只需要借助Microsoft.Extensions.Localization包就可以完成一个最简单的本地化功能。实现过程分为:1)引入本地化依赖注入;2)添加资源文件;3)本地化配置。

实现

引入本地化依赖注入

为了验证静态字符串的本地化功能,我们在TodoListController中注入本地化IStringLocalizer<T>功能并新增一个演示接口:

  • TodoListController.cs
private readonly IStringLocalizer<TodoListController> _localizer;

public TodoListController(IMediator mediator, IStringLocalizer<TodoListController> localizer)
{
    _mediator = mediator;
    _localizer = localizer;
}

// .....

[HttpGet("meta")]
public ApiResponse<string> GetTodoListMeta()
{
    var response = ApiResponse<string>.Success(_localizer["TodoListMeta"]);
    return response;
}

添加资源文件

我们在Api项目中添加资源文件作为演示目的,新建Resources文件夹,并新增两个文件Controllers.TodoListController.en-us.resxControllers.TodoListController.zh.resx

在资源编辑器中可以对其进行编辑:

在对应的resx文件中生成的位置:

<data name="TodoListMeta" xml:space="preserve">
    <value>This is a TodoList Controller</value>
</data>

<data name="TodoListMeta" xml:space="preserve">
    <value>这是一个TodoList应用控制器</value>
</data>

添加本地化配置

最后我们在Program中对本地化进行配置:

  • Program.cs
// 引入本地化服务
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");

// 省略其他...

// 引入本地化中间件
var supportedCultures = new[] { "en-US", "zh" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

app.MapDefaultControllerRoute();

验证

启动Api项目,执行获取TodoList/meta的请求:

验证1: 请求不携带任何Culture信息

则使用默认配置的en-US

验证2: 请求携带culture=en-us查询字符串#

指定使用en-Us

验证3: 请求携带culture=zh查询字符串#

指定使用zh

可以看到我们可以根据不同的culture对应返回本地化后的字符串内容。

总结#

关于静态字符串的本地化功能本文只做了最基础的介绍,此外还可以通过DataAnnotation的方式对Dto的属性字段进行本地化控制,微软的官方文档可以作为不同应用场景的参考:Globalization and localization in ASP.NET Core

因为在实际开发中,如果需要大量用到本地化(Localization)的功能,那么提供国际化(Globalization)也是必要的,并且这两个方面在实现上一般都会借助更为成熟的框架(例如ABP)使用已经包装好的模块功能。所以文章不做过多展开,上面提供的官方文档已经足以应对日常的开发。

下一篇文章我们会将应用程序使用Docker进行打包,并且向容器中添加证书以实现HTTPS方式访问。

参考资料

  1. Globalization and localization in ASP.NET Core