ASP.NET Core 本地化技巧，让你的应用瞬间支持多语言

大家好，我是深山踏红叶，今天我们来聊一聊本地化（Localization）, 在开发中本地化也是一个非常重要的方面。Dotnet平台也提供了强大的本地化支持，能够帮助我们根据用户的语言和区域设置提供多语言支持，提高用户体验。下面我们来聊 ASP.NET Core 中的本地化功能，如何配置及如何在应用程序中实现它。

术语

• • 全球化 (G11N)：使应用支持不同语言和区域的过程。 缩写来自第一个和最后一个字母以及它们之间的字母数。
• • 本地化 (L10N)：针对特定语言和区域自定义全球化应用的过程。
• • 国际化 (I18N)：包括全球化和本地化。
• • 区域性：一种语言和/或区域。
• • 非特定区域性：具有指定语言但不具有区域的区域性（例如“en”、“es”）。
• • 特定区域性：具有指定语言但和区域的区域性（例如“en-US”、“en-GB”、“es-CL”）。
• • 父区域性：包含特定区域性的非特定区域性。（例如，“en”是“en-US”和“en-GB”的父区域性）。
• • 区域设置：区域设置与区域性相同。

ASP.NET Core 添加本地化支持

在 ASP.NET Core 中，启用本地化功能首先需要在 Startup.cs 中进行配置。

在服务容器中添加本地化服务：

在 ConfigureServices 方法中添加本地化服务：

public void ConfigureServices(IServiceCollection services)
{
    //指定资源文件的存放位置
    services.AddLocalization(options => options.ResourcesPath = "Resources");
    services.AddControllersWithViews()
        .AddViewLocalization()
        .AddDataAnnotationsLocalization();
} 
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    var supportedCultures = new[] { "en-US", "zh-CN" };
    var localizationOptions = new RequestLocalizationOptions()
         //默认文化设置
        .SetDefaultCulture("en-US")
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);

    app.UseRequestLocalization(localizationOptions);

    app.UseStaticFiles();
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

1. 1. 资源文件配置

• • 使用 AddLocalization 方法设置资源文件的根目录，并注册本地化服务，如 IStringLocalizer<> 和 IStringLocalizerFactory。

1. 2. 数据注解本地化
   • • 使用 AddDataAnnotationsLocalization 方法注册数据注解本地化服务，主要通过设置 DataAnnotationLocalizerProvider 委托来实现。
2. 3. 视图本地化
   • • 使用 AddViewLocalization 方法注册视图本地化服务，包括 IViewLocalizer、IHtmlLocalizer<> 和 IHtmlLocalizerFactory。
3. 4. 请求本地化中间件
   • • 使用 UseRequestLocalization 启用 RequestLocalizationMiddleware，该中间件可以从请求中解析区域文化信息（Culture）并设置到当前线程中。
4. 5. 支持的语言配置
   • • 使用 AddSupportedCultures 和 AddSupportedUICultures 配置应用支持的 Culture 和 UICulture。
5. 6. 默认语言配置
   • • 使用 SetDefaultCulture 设置应用的默认 Culture。

创建资源文件: 资源文件（.resx）用于存储不同语言的文本。创建 Resources 文件夹，为每种支持的语言创建不同的资源文件。

• • Resources/Controllers/WeatherForecastController.resx：默认语言资源文件 。
• • Resources/Controllers/WeatherForecastController.zh-CN.resx：简体中文资源文件。
• • Resources/Controllers/WeatherForecastController.fr-FR.resx：法语资源文件。

默认的情况需要对应相对应的文件路径，为了优雅地使用共享资源，我们在项目根目录下创建SharedResource伪类，用来代理共享资源。

使用本地化文本

使用 IStringLocalizer

    [ApiController]
    [Route("[controller]")]
    publicclassWeatherForecastController : ControllerBase
    {
         
        privatereadonly IStringLocalizer<WeatherForecastController> _localizer;
        privatereadonly IStringLocalizer<SharedResource> _sharedLocalizer;
        public WeatherForecastController( IStringLocalizer<WeatherForecastController> localizer, IStringLocalizer<SharedResource> sharedLocalizer)
        { 
            _localizer = localizer;
            _sharedLocalizer = sharedLocalizer;
        }

       

        [HttpGet(Name = "GetWeatherForecast")] 
        public IActionResult Index()
        {
            var content = $"当前区域文化：{CultureInfo.CurrentCulture.Name}\n" +
       $"{_localizer["NetName"]}\n" +
       $"{_sharedLocalizer["CurrentTime"]}{DateTime.Now.ToLocalTime()}\n";
            return Content(content);
        }
    } 

当前区域文化：zh-CN NetName CurrentTime ：2025/3/1 18:19:13

访问：https://localhost:7256/WeatherForecast?culture=en-US

当前区域文化：en-US NetName CurrentTime3/1/2025 6:24:57 PM

1. 1. IStringLocalizer 和 IStringLocalizer<>
   • • 功能：用于文本本地化，是最常用的本地化器。
   • • 获取方式：可以通过依赖注入直接获取，也可以通过 IStringLocalizerFactory 创建。
   • • 关系：IStringLocalizer<> 是对 IStringLocalizer 的封装，提供了更灵活的本地化方式。
2. 2. IHtmlLocalizer 和 IHtmlLocalizer<>
   • • 功能：用于本地化 HTML 文本，不会对 HTML 标签进行编码。
   • • 获取方式：同样支持依赖注入或通过 IHtmlLocalizerFactory 创建。
3. 3. IViewLocalizer
   • • 功能：专门用于视图（前端页面）的本地化。

使用本地化字符串标记

在视图文件中，你还可以直接使用 @localizer 标签获取本地化的文本：

@inject IStringLocalizer<SharedResource> localizer
<h1>@localizer["WelcomeMessage"]</h1>

请求文化提供程序（RequestCultureProvider）

ASP.NET Core 默认提供了以下三种请求文化提供程序，用于解析请求中的语言信息：

1. 1. QueryStringRequestCultureProvider
   • • 通过查询字符串参数 culture 和 ui-culture 设置语言，例如：?culture=zh-CN&ui-culture=zh-CN。
2. 2. CookieRequestCultureProvider
   • • 通过 Cookie 中的键 .AspNetCore.Culture 设置语言，值格式为 c=zh-CN|uic=zh-CN。
3. 3. AcceptLanguageHeaderRequestCultureProvider
   • • 从 HTTP 请求头中的 Accept-Language 字段读取语言信息。

总结

参考：https://www.cnblogs.com/xiaoxiaotank/p/17466952.html

https://learn.microsoft.com/zh-cn/aspnet/core/blazor/globalization-localization?view=aspnetcore-9.0

ASP.NET Core 提供了强大的本地化功能，通过灵活配置本地化服务和请求文化提供程序，可以轻松实现国际化支持。同时，支持自定义扩展和资源文件格式切换，满足不同开发场景的需求