1. 项目缘起为什么你的应用需要多语言支持几年前我接手一个内部工具项目当时只支持中文团队用着也挺好。后来公司业务拓展到海外突然有一天产品经理跑过来说“下个月我们要给东南亚的客户做演示界面和文档需要支持英文和泰语。” 那一刻我才真正体会到“国际化”i18n和“本地化”l10n不是可选项而是业务发展到一定阶段的必然需求。在 Asp .Net Core 框架下构建支持多语言的应用远不止是把界面上的文字替换成另一种语言那么简单它涉及到资源文件的管理、文化区域的自动识别、动态切换以及整个开发流程的适配。简单来说国际化就是让你的应用程序具备处理多种语言和文化习惯如日期、货币格式的能力而本地化则是为特定的语言区域如en-US,zh-CN提供翻译好的资源。对于现代Web应用无论是面向全球用户的电商平台、SaaS服务还是企业内部需要支持多地区团队的管理系统多语言支持都是提升用户体验、拓展市场的基础能力。Asp .Net Core 从设计之初就内置了对国际化的良好支持通过IStringLocalizer、IHtmlLocalizer等接口和中间件我们可以相对优雅地实现这一功能避免在代码中硬编码字符串。但根据我的经验很多开发者在配置多语言时容易陷入几个误区要么把所有资源都堆在一个巨大的JSON文件里后期维护灾难要么忽略了请求文化Culture的自动解析逻辑导致切换不生效再或者没有处理好共享资源与页面特定资源的关系。接下来我将结合一个从零开始的实战项目拆解 Asp .Net Core 国际化多语言配置的核心步骤、原理以及那些官方文档可能没细说的“坑”。2. 环境搭建与基础项目结构规划在开始编码之前合理的项目结构能让你后续的维护工作轻松十倍。我建议创建一个全新的 Asp .Net Core MVC 项目作为演示但其中的核心配置同样适用于 Web API 或 Razor Pages 项目。首先使用命令行或 IDE 创建一个新项目dotnet new mvc -n LocalizationDemo cd LocalizationDemo创建完成后我们首要任务是规划资源文件的存放位置。Asp .Net Core 支持多种资源存储方式最常见的是.resx文件和 JSON 文件。.resx是 .NET 传统的二进制资源格式与 Visual Studio 集成度好而 JSON 文件更轻量易于版本控制和跨平台编辑。为了更贴近现代开发流程我选择使用 JSON 文件。在项目根目录下创建以下文件夹结构LocalizationDemo/ ├── Resources/ │ ├── Controllers/ │ │ ├── HomeController.en.json │ │ ├── HomeController.zh.json │ │ └── HomeController.fr.json │ ├── Views/ │ │ └── Home/ │ │ ├── Index.en.json │ │ ├── Index.zh.json │ │ └── Index.fr.json │ └── Shared/ │ ├── _Layout.en.json │ ├── _Layout.zh.json │ ├── _Menu.en.json │ └── _Menu.fr.json └── ...这种按“功能模块/页面”组织资源的方式相比把所有字符串放在一个全局文件里优势非常明显。当你要修改首页的某个按钮文字时你很清楚只需要去Resources/Views/Home/Index.[culture].json里找不会影响到用户管理或订单页面的文案。这对于大型项目、团队协作以及后续的翻译外包工作都非常友好。接下来我们需要安装一个关键的 NuGet 包来支持 JSON 资源文件。虽然 Asp .Net Core 内置了对IStringLocalizer的支持但其默认的资源查找逻辑主要针对.resx文件。为了使用 JSON我们可以使用Microsoft.Extensions.Localization包它已经包含在元包中但为了更灵活地配置我们显式地添加对资源文件的支持。实际上对于 JSON 文件我们通常需要实现一个自定义的IStringLocalizerFactory但社区已有成熟的方案。一个更简单直接的方法是使用Microsoft.Extensions.Localization配合特定的资源路径配置。在本例中我们将使用内置机制通过配置让其能读取我们指定目录下的 JSON 文件。首先在Program.cs中我们需要添加和配置本地化服务。这是整个多语言体系的“发动机”。3. 核心服务配置Program.cs 中的初始化逻辑所有的魔法都始于启动配置。打开Program.cs文件在builder.Services的服务容器配置区域添加本地化服务。这里有几个关键点需要理解。第一步添加本地化服务var builder WebApplication.CreateBuilder(args); // 添加 MVC 服务如果新建项目已默认添加 builder.Services.AddControllersWithViews(); // 配置本地化服务 builder.Services.AddLocalization(options options.ResourcesPath Resources);ResourcesPath Resources这行代码至关重要。它告诉 Asp .Net Core 的本地化系统“请去项目根目录下的Resources文件夹里寻找资源文件。” 系统会基于这个路径按照约定的命名规则去查找文件。对于 JSON 文件我们需要后续的配置来指定使用哪种资源格式。第二步配置请求本地化中间件服务添加后还需要告诉应用如何根据每个 HTTP 请求来确定应该使用哪种语言文化。这通过配置请求本地化选项和添加中间件来实现。// 配置支持的 cultures语言文化列表 const string defaultCulture en-US; var supportedCultures new[] { new CultureInfo(defaultCulture), new CultureInfo(zh-CN), new CultureInfo(fr-FR) }; builder.Services.ConfigureRequestLocalizationOptions(options { options.DefaultRequestCulture new RequestCulture(defaultCulture); options.SupportedCultures supportedCultures; // 用于日期、数字、货币格式 options.SupportedUICultures supportedCultures; // 用于查找资源文件UI字符串 options.RequestCultureProviders new ListIRequestCultureProvider { // 优先级1QueryStringRequestCultureProvider通过查询字符串切换如 ?cultureen-US new QueryStringRequestCultureProvider(), // 优先级2CookieRequestCultureProvider通过Cookie持久化语言选择 new CookieRequestCultureProvider(), // 优先级3AcceptLanguageHeaderRequestCultureProvider根据浏览器语言偏好 new AcceptLanguageHeaderRequestCultureProvider() }; });这段代码做了几件重要的事定义支持的语言我们声明支持美式英语 (en-US)、简体中文 (zh-CN) 和法语 (fr-FR)。CultureInfo对象包含了特定区域的语言和格式规则。设置默认文化当系统无法从请求中确定用户语言时将回退到en-US。区分 Culture 与 UICultureSupportedCultures影响区域性相关的功能如DateTime.ToString()的格式而SupportedUICultures专门用于查找本地化的字符串资源。大多数情况下两者设为相同列表即可。配置文化提供者顺序这是一个非常实用的策略。它定义了系统尝试获取用户语言偏好的顺序。顺序决定了优先级。QueryStringRequestCultureProvider最高优先级。用户访问?culturezh-CNui-culturezh-CN可以立即切换语言常用于开发测试或用户手动选择后的跳转链接。CookieRequestCultureProvider次优先级。一旦用户通过某种方式比如查询字符串选择了语言我们可以将选择写入 Cookie这样用户下次访问时无需再次选择。这是实现持久化语言偏好的关键。AcceptLanguageHeaderRequestCultureProvider最低优先级。读取浏览器发送的Accept-LanguageHTTP 头。这是最自动化的方式但用户可能不清楚如何修改浏览器设置且优先级最低确保了手动选择的权力。第三步启用请求本地化中间件配置好选项后必须在请求管道中启用它而且位置很关键。它应该放在处理路由和端点的中间件之前以确保在 MVC 开始执行控制器动作之前当前请求的文化信息就已经被确定。var app builder.Build(); // 配置 HTTP 请求管道 if (!app.Environment.IsDevelopment()) { app.UseExceptionHandler(/Home/Error); app.UseHsts(); } app.UseHttpsRedirection(); app.UseStaticFiles(); // *** 启用请求本地化中间件 *** app.UseRequestLocalization(); // 这会自动使用我们上面 ConfigureRequestLocalizationOptions 的配置 app.UseRouting(); app.UseAuthorization(); app.MapControllerRoute( name: default, pattern: {controllerHome}/{actionIndex}/{id?}); app.Run();至此服务的配置就完成了。但我们现在只有“发动机”还没有“燃料”即资源文件。接下来我们创建具体的资源文件并了解其命名规范。4. 资源文件创建、命名规范与内容组织资源文件是翻译内容的载体。Asp .Net Core 查找资源文件的规则基于一个“资源名称”通常是类的全名或视图的路径和当前UICulture。对于控制器和普通类系统会查找名为[Namespace].[ClassName].[culture].json的资源文件。例如对于LocalizationDemo.Controllers.HomeController类系统会查找Resources/Controllers/HomeController.en-US.json。为了简化我们通常使用不带区域的“中性文化”文件名如HomeController.en.json系统会自动匹配en-US或en-GB。对于视图系统会查找与视图路径匹配的资源文件。例如对于/Views/Home/Index.cshtml视图系统会查找Resources/Views/Home/Index.[culture].json。让我们创建第一个资源文件。在Resources/Views/Home/目录下创建Index.en.json{ Title: Welcome, HelloWorld: Hello, world!, CurrentTime: The current server time is: {0}, LearnMore: Learn More }接着创建对应的中文文件Index.zh.json{ Title: 欢迎, HelloWorld: 你好世界, CurrentTime: 当前服务器时间是{0}, LearnMore: 了解更多 }以及法语文件Index.fr.json{ Title: Bienvenue, HelloWorld: Bonjour le monde !, CurrentTime: Lheure actuelle du serveur est : {0}, LearnMore: En savoir plus }注意CurrentTime中的{0}这是一个占位符允许我们在运行时传入动态值如实际的日期时间这是资源字符串的常见需求。注意JSON 文件的属性名如Title是大小写敏感的必须与你在视图中引用的键名完全一致。一个常见的错误是键名拼写不一致导致回退到默认语言甚至抛出异常。5. 在视图中使用 IStringLocalizer三种注入方式配置好服务和资源后就可以在视图中使用本地化的字符串了。Asp .Net Core 提供了IStringLocalizerT泛型接口其中T通常是与之关联的类。对于视图通常使用IViewLocalizer它是IStringLocalizer的视图特化版本能自动根据视图路径定位资源文件。方式一使用依赖注入在视图中获取 IViewLocalizer这是最直接的方式。在视图文件如Index.cshtml的顶部通过inject指令注入IViewLocalizerusing Microsoft.AspNetCore.Mvc.Localization inject IViewLocalizer Localizer然后在 HTML 中使用Localizer对象{ ViewData[Title] Localizer[Title]; } div classtext-center h1 classdisplay-4Localizer[HelloWorld]/h1 pstring.Format(Localizer[CurrentTime], DateTime.Now)/p a href# classbtn btn-primaryLocalizer[LearnMore]/a /divLocalizer[Key]会返回一个LocalizedString对象在 Razor 中直接输出时其Value属性会自动被调用显示当前语言下的字符串。对于带占位符的字符串我们使用string.Format方法进行格式化。方式二在控制器中注入并传递到视图有时你可能需要在控制器逻辑中获取本地化字符串然后再传递给视图。在HomeController.cs中using Microsoft.AspNetCore.Mvc; using Microsoft.Extensions.Localization; namespace LocalizationDemo.Controllers { public class HomeController : Controller { private readonly IStringLocalizerHomeController _localizer; public HomeController(IStringLocalizerHomeController localizer) { _localizer localizer; } public IActionResult Index() { ViewData[Greeting] _localizer[HelloWorld]; ViewData[FormattedTime] string.Format(_localizer[CurrentTime], DateTime.Now); return View(); } } }然后在视图中你可以通过ViewData访问这些已经翻译好的字符串。这种方式将本地化逻辑放在了控制器视图更干净但增加了控制器的复杂度。方式三使用共享资源对于多个控制器或视图共用的字符串比如网站名称、通用按钮文字“提交”、“取消”创建共享资源是更好的选择。首先创建一个空的类作为共享资源的标记。在项目根目录创建SharedResource.csnamespace LocalizationDemo { // 这是一个标记类仅用于定位共享资源文件。 public class SharedResource { } }然后在Resources/目录下创建SharedResource.en.json、SharedResource.zh.json等文件。在任何需要的地方注入IStringLocalizerSharedResource即可使用共享的字符串。实操心得我强烈建议为每个视图和控制器创建独立的资源文件仅将真正的全局字符串放入共享资源。这能最大程度地保持模块化避免一个资源文件的改动影响过多地方在大型项目中尤其重要。6. 实现前端语言切换器与 Cookie 持久化一个友好的多语言网站必须提供直观的语言切换方式。我们将创建一个简单的语言切换下拉菜单并利用 Cookie 来记住用户的选择。首先我们在_Layout.cshtml或一个共享的局部视图中创建切换器。为了获取当前支持的语言列表我们需要将之前在Program.cs中配置的RequestLocalizationOptions注入进来。修改_Layout.cshtml的头部using Microsoft.AspNetCore.Localization using Microsoft.Extensions.Options inject IOptionsRequestLocalizationOptions LocOptions { var requestCulture Context.Features.GetIRequestCultureFeature(); var cultureItems LocOptions.Value.SupportedUICultures .Select(c new SelectListItem { Value c.Name, Text c.DisplayName }) .ToList(); var returnUrl string.IsNullOrEmpty(Context.Request.Path) ? ~/ : $~{Context.Request.Path.Value}{Context.Request.QueryString}; }然后在导航栏合适的位置比如右上角添加一个表单div classnav-item dropdown form idcultureForm asp-controllerHome asp-actionSetLanguage asp-route-returnUrlreturnUrl methodpost select nameculture onchangethis.form.submit() classform-control form-control-sm foreach (var item in cultureItems) { option valueitem.Value selected(requestCulture?.RequestCulture?.UICulture?.Name item.Value) item.Text /option } /select /form /div这个表单包含一个下拉选择框选项来自SupportedUICultures。当用户选择不同选项时通过onchange事件自动提交表单。表单会提交到HomeController的SetLanguage动作并携带当前页面 URL 作为returnUrl以便语言切换后能回到原页面。现在在HomeController中实现SetLanguage动作方法[HttpPost] public IActionResult SetLanguage(string culture, string returnUrl) { // 验证请求的文化是否在支持列表中 var supportedCultures new[] { en-US, zh-CN, fr-FR }; if (!supportedCultures.Contains(culture)) { culture en-US; // 回退到默认 } // 将用户选择的 Culture 存入 Cookie Response.Cookies.Append( CookieRequestCultureProvider.DefaultCookieName, CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)), new CookieOptions { Expires DateTimeOffset.UtcNow.AddYears(1), IsEssential true } // 设置长期有效 ); // 重定向回原页面 return LocalRedirect(returnUrl); }这个方法的核心是Response.Cookies.Append。我们使用CookieRequestCultureProvider.DefaultCookieName默认为.AspNetCore.Culture作为 Cookie 的名称并使用MakeCookieValue方法生成符合中间件解析格式的 Cookie 值。设置IsEssential true是为了确保即使用户拒绝了非必要 Cookie这个语言选择 Cookie 依然能被写入这对核心功能至关重要。踩坑点LocalRedirect方法会防止开放重定向攻击确保returnUrl是应用内的本地 URL。直接使用Redirect(returnUrl)是不安全的。完成以上步骤后运行应用。你应该能看到页面右上角有一个语言下拉框。选择“中文简体中国”后页面内容应即时切换为中文并且刷新页面或关闭浏览器再打开语言选择依然有效这就是 Cookie 持久化的作用。7. 高级话题资源文件回退机制与结构化 JSON在实际开发中你不可能为每个语言都翻译所有字符串。Asp .Net Core 的本地化系统提供了智能的回退机制。特定文化回退到中性文化当请求fr-FR法国法语时系统会按顺序查找Resource.fr-FR.jsonResource.fr.json回退到中性法语Resource.en.json或你设置的默认文化资源最后如果都找不到直接返回键名本身避免抛出异常便于开发。父资源回退对于视图资源如果在Resources/Views/Home/Index.fr.json中找不到某个键系统会去父目录或共享资源中查找吗默认行为不会。视图本地化器 (IViewLocalizer) 严格限定在对应视图路径的资源文件中查找。这是为了保持明确的边界。如果你希望共享应该使用IStringLocalizerSharedResource。结构化 JSON 资源对于复杂的 UI有时一个键对应的不是简单字符串而是一段带有 HTML 或复杂格式的文本。你可以这样做{ PromoBanner: { Title: Summer Sale!, Description: Up to strong50% off/strong on selected items. a href/salesShop now/a., CssClass: alert-success } }在视图中你可以通过Localizer[PromoBanner.Title]来访问嵌套属性。但请注意如果值中包含 HTML在输出时需要使用Html.Raw(Localizer[PromoBanner.Description])来防止 Razor 自动进行 HTML 编码。务必谨慎使用Html.Raw并确保资源文件的内容是可信的以防止跨站脚本XSS攻击。更好的做法是将样式和结构留在视图中资源文件只提供纯文本内容。8. 常见问题排查与调试技巧即使按照步骤配置有时多语言功能也可能不生效。以下是我总结的几个常见问题及排查思路问题一切换语言后页面内容没有变化。检查点1Cookie 是否成功写入。打开浏览器的开发者工具F12在“应用”Application或“存储”Storage标签页中查看 Cookies。你应该能看到一个名为.AspNetCore.Culture的 Cookie其值类似于cen-US|uicen-US。如果没有检查SetLanguage动作是否被正确调用以及 Cookie 设置代码是否有误。检查点2中间件顺序。确保app.UseRequestLocalization()在app.UseRouting()和app.UseEndpoints()之前。如果顺序错了路由已经确定了控制器和动作此时再设置文化可能就晚了。检查点3资源文件命名和位置。确认资源文件是否放在Resources文件夹或你配置的ResourcesPath的正确子目录下并且文件名完全匹配包括大小写。例如对于HomeController文件应为Resources/Controllers/HomeController.en.json而不是Resources/Controllers/HomeController.en-US.json除非你请求的就是en-US。问题二某些字符串显示为键名如“HelloWorld”而不是翻译后的文本。检查点1键名拼写。确认视图中Localizer[Key]里的Key与 JSON 文件中的属性名完全一致包括大小写。检查点2资源文件是否被发布。在开发环境下修改 JSON 文件通常能热重载。但在生产环境如发布到 IIS你需要确保资源文件被包含在发布输出中。检查.csproj文件确保类似以下内容存在或者所有.json文件的“复制到输出目录”属性设置为“始终复制”或“如果较新则复制”。ItemGroup Content UpdateResources\** CopyToOutputDirectoryPreserveNewest / /ItemGroup检查点3回退行为。系统找不到对应语言的翻译时会尝试回退到中性文化再回退到默认文化资源。如果连默认文化资源文件里都没有这个键那么就会返回键名本身。请检查你的默认文化如en.json资源文件是否包含了所有必需的键。问题三日期、货币格式没有随语言切换。检查点确认你在RequestLocalizationOptions中同时正确设置了SupportedCultures和SupportedUICultures。SupportedCultures控制CultureInfo.CurrentCulture它影响DateTime.ToString()、decimal.ToString(“C”)等格式。如果只设置了SupportedUICultures那么字符串翻译会变但数字日期格式不会变。调试技巧你可以在视图中临时添加调试代码来查看当前的文化信息pCurrent Culture: System.Globalization.CultureInfo.CurrentCulture.Name/p pCurrent UI Culture: System.Globalization.CultureInfo.CurrentUICulture.Name/p pRequest Culture Provider: Context.Features.GetIRequestCultureFeature()?.Provider?.GetType().Name/p这能帮你快速确认当前生效的文化是哪个以及是由哪个 Provider查询字符串、Cookie 还是浏览器头提供的。9. 在 Web API 与类库中的本地化实践多语言需求不仅限于 MVC 视图在 Web API 控制器和共享的类库中同样常见。在 Web API 控制器中用法与 MVC 控制器完全一样。注入IStringLocalizerT然后在返回错误信息、状态描述时使用本地化字符串。[ApiController] [Route(api/[controller])] public class ProductsController : ControllerBase { private readonly IStringLocalizerProductsController _localizer; public ProductsController(IStringLocalizerProductsController localizer) { _localizer localizer; } [HttpGet({id})] public IActionResult Get(int id) { var product _productService.Get(id); if (product null) { // 返回本地化的错误信息 return NotFound(_localizer[ProductNotFound, id]); } return Ok(product); } }你需要为ProductsController创建对应的资源文件Resources/Controllers/ProductsController.[culture].json。在独立的类库中如果你想在一个被多个项目引用的类库中实现本地化最佳实践是在类库项目中创建Resources文件夹和资源文件。为需要本地化的类创建对应的资源文件例如MyUtilityClass.en.json。在类库中通过依赖注入获取IStringLocalizerMyUtilityClass。如果类库本身不处理依赖注入通常由调用方如主 Web 项目在构造服务时传入IStringLocalizer实例。关键一步确保类库中的资源文件能被主项目发现。你需要修改主项目的.csproj文件添加对类库资源文件的引用或者确保类库的资源文件被复制到主项目的输出目录。一种更清晰的方式是将资源文件作为“嵌入式资源”嵌入类库的 DLL 中然后使用IStringLocalizerFactory从程序集中读取。但这涉及更高级的配置对于大多数场景将资源文件放在主项目中统一管理可能更简单。10. 性能考量与最佳实践总结当资源文件非常多时可能会对性能产生轻微影响尤其是在应用启动时加载所有资源。以下是一些优化建议按需加载Asp .Net Core 的本地化系统默认是惰性加载的只有在第一次请求某个本地化器 (IStringLocalizer) 时才会加载对应的资源文件。这本身就是一个优化。避免巨型资源文件坚持按功能模块拆分资源文件而不是使用一个全局文件。这不仅能提高可维护性也能减少单次加载和解析的数据量。使用缓存翻译内容本质上是静态的在发布后。虽然本地化框架内部可能有缓存机制但在极高并发场景下可以考虑使用分布式缓存如 Redis来存储常用的、翻译结果固定的字符串但这会引入缓存一致性问题更新翻译后需要清除缓存。预编译资源对于.resx文件.NET 支持在编译时生成强类型资源类这能提供编译时检查和高性能。对于 JSON 文件没有直接的预编译支持但其文本格式在解析上通常也足够快。监控缺失的翻译在开发阶段可以注册一个MissingTranslation事件或通过自定义IStringLocalizer实现来记录哪些键没有找到对应语言的翻译方便查漏补缺。回顾整个配置过程从服务注册、中间件配置、资源文件组织、视图注入到语言切换器实现每一步都有其设计用意。我个人的体会是前期花时间设计好资源文件的结构和命名规范远比后期在混乱的翻译中挣扎要高效得多。对于大多数项目使用 JSON 文件、按视图/控制器组织资源、配合 Cookie 持久化的语言切换器是一个平衡了灵活性、可维护性和开发体验的方案。当你的应用需要走向世界时这套建立在 Asp .Net Core 之上的多语言体系将成为你坚实的后盾。