在ASP.NET Core中实现多语言本地化与国际化支持的详细步骤
你好，我是源码库的技术博主。今天我们来聊聊一个在构建全球化应用时无法绕开的话题：多语言本地化（Localization）与国际化（Internationalization，简称 i18n）。回想我第一次为项目添加多语言支持时，面对资源文件、文化代码和中间件配置，确实有点手忙脚乱。但一旦理清脉络，ASP.NET Core 提供的这套本地化框架其实相当优雅和强大。本文我将结合自己的实战经验，带你一步步从零开始，在ASP.NET Core应用中搭建坚实的多语言支持，并分享一些我踩过的“坑”和最佳实践。
第一步：项目基础配置与服务的注入
万事开头难，但第一步其实很简单。首先，我们需要在 Program.cs 中配置本地化所需的服务。ASP.NET Core 的本地化主要依赖于 IStringLocalizer 和 IStringLocalizer 这些服务。
// 这是一个概念性步骤，实际代码在Program.cs中
// 我们需要使用 NuGet 包管理器控制台或 CLI 添加必要的包。
// 通常，Microsoft.AspNetCore.Localization 是核心。
现在，打开你的 Program.cs 文件，添加以下服务配置：
var builder = WebApplication.CreateBuilder(args);
// 添加本地化服务，并设置资源文件路径（Resources）。
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");
// 配置 MVC/Controllers 时（如果使用），添加视图本地化与数据注解本地化。
builder.Services.AddControllersWithViews()
.AddViewLocalization() // 支持视图本地化
.AddDataAnnotationsLocalization(); // 支持模型验证消息本地化
// 配置应用支持的文化（语言）
var supportedCultures = new[] { "en-US", "zh-CN", "fr-FR" }; // 定义支持的语言
var localizationOptions = new RequestLocalizationOptions()
.SetDefaultCulture(supportedCultures[0]) // 设置默认文化
.AddSupportedCultures(supportedCultures) // 设置支持的文化
.AddSupportedUICultures(supportedCultures); // 设置支持的UI文化
var app = builder.Build();
// 使用请求本地化中间件，这是关键！
app.UseRequestLocalization(localizationOptions);
踩坑提示：UseRequestLocalization 中间件必须放在其他中间件（如 UseRouting）之前，因为它需要最早处理请求的文化信息，以便后续中间件和管道能使用正确的语言。我曾经把它放错位置，导致整个页面的语言切换完全失效，排查了好久。
第二步：创建资源文件（.resx）
资源文件是存储不同语言文本的核心。在项目根目录下创建名为 Resources 的文件夹（与上一步 ResourcesPath 对应）。
假设我们有一个 HomeController，需要对其中的字符串进行本地化。标准的做法是创建与控制器或视图同名的资源文件。例如：
项目结构示意：
- Resources
- Controllers
- HomeController.en-US.resx (默认/英文)
- HomeController.zh-CN.resx (中文)
- HomeController.fr-FR.resx (法文)
- Views
- Home
- Index.en-US.resx
- Index.zh-CN.resx
更常见的做法是使用共享的全局资源文件。我们创建一个 SharedResource 类（一个空的类即可，仅用于标记），然后创建 SharedResource.en-US.resx 等文件。
// 在项目任意位置创建，例如 Models/SharedResource.cs
namespace MyWebApp.Models;
public class SharedResource { }
然后在 Resources 文件夹下创建 SharedResource.en-US.resx。打开资源文件编辑器，添加名称（Key）和值（Value）。例如，在英文文件中添加 WelcomeMessage 为 “Welcome!”，在中文文件 SharedResource.zh-CN.resx 中添加同名的 WelcomeMessage 为 “欢迎！”。务必确保所有语言的 .resx 文件中的 Key 完全一致。
第三步：在控制器和视图中使用本地化服务
配置好资源后，就可以在代码中使用了。
在控制器中：通过依赖注入获取 IStringLocalizer。
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;
namespace MyWebApp.Controllers;
public class HomeController : Controller
{
private readonly IStringLocalizer _localizer;
public HomeController(IStringLocalizer localizer)
{
_localizer = localizer;
}
public IActionResult Index()
{
ViewData["Welcome"] = _localizer["WelcomeMessage"]; // 通过Key获取本地化字符串
return View();
}
}
在Razor视图中：首先在视图顶部注入本地化器，或者使用内置的全局 IViewLocalizer。
@* 在 Views/Home/Index.cshtml 顶部 *@
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@Localizer["WelcomeMessage"]
@ViewData["Welcome"]
@* 或者直接使用共享资源的本地化器 *@
@inject IStringLocalizer SharedLocalizer
@SharedLocalizer["AnotherKey"]
实战经验：对于简单的、仅在视图中使用的字符串，使用 IViewLocalizer 很方便，它会自动查找与当前视图同名的资源文件。但对于跨控制器、视图、服务共享的字符串（如按钮文本、错误消息），强烈建议使用基于 SharedResource 的 IStringLocalizer，这样更易于管理和维护。
第四步：实现语言切换器
用户需要一个UI来切换语言。通常，我们在布局（_Layout.cshtml）中创建一个语言选择下拉菜单。其核心原理是将用户选择的语言文化代码（如 “zh-CN”）持久化到Cookie中，RequestLocalizationMiddleware 会读取这个Cookie来确定当前请求的文化。
首先，创建一个控制器动作来处理语言切换：
// 在 HomeController 或专门的 CultureController 中
[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
// 将用户选择的语言文化保存到Cookie
Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName, // ".AspNetCore.Culture"
CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
);
// 重定向回原页面，此时中间件会读取新的Cookie并应用语言
return LocalRedirect(returnUrl);
}
然后，在视图中创建语言切换表单：
English
中文
Français
踩坑提示：LocalRedirect 方法可以防止开放重定向攻击，务必使用它而不是简单的 Redirect。另外，确保 returnUrl 是经过验证的本地URL。
第五步：高级话题与最佳实践
1. 模型验证消息的本地化：我们在第一步已经添加了 AddDataAnnotationsLocalization()。现在，你可以在模型属性上使用 [Display(Name = "Key")]，并在资源文件中为 “Key” 提供翻译。错误消息也可以本地化，需要为 IStringLocalizer 注册模型类，例如 services.AddSingleton<IStringLocalizer, StringLocalizer>();（更现代的方式是让框架自动处理）。
2. URL文化提供者：除了Cookie，你还可以通过URL路径（如 /zh-CN/Home/Index）或查询字符串来指定文化。这需要在 RequestLocalizationOptions 中配置：
localizationOptions.AddInitialRequestCultureProvider(
new RouteDataRequestCultureProvider { Options = localizationOptions }
);
// 同时需要配置相应的路由模板，例如 `{culture?}/{controller=Home}/{action=Index}/{id?}`
3. 缺少资源时的回退策略：默认情况下，如果找不到某个Key在当前文化下的翻译，会直接返回Key本身。这有助于开发阶段发现遗漏的翻译。你可以通过配置 LocalizationOptions 来改变这一行为。
4. 保持资源文件同步：随着项目迭代，新增或删除Key是常事。我强烈建议使用工具或编写简单的脚本，来对比不同语言的 .resx 文件，确保Key的一致性。手动维护很容易出错。
总结一下，在ASP.NET Core中实现多语言支持是一个系统性的工程，涉及服务注册、资源管理、UI集成和请求处理管道。从我的经验来看，前期规划好资源文件的结构（是全局共享还是按功能模块划分）至关重要，这能避免后期的重构痛苦。希望这篇详细的指南能帮助你顺利地为你的应用插上国际化的翅膀。如果在实践中遇到问题，欢迎在源码库社区交流讨论！
评论(0)