5. 国际化
国际化的应用程序以用户的语言显示其文本。案例研究提供法语和英语两种语言。原理很简单:视图中不再包含文本,而是包含键 ([MENU.HOME]),并且每种语言都有一个字典 ,为每个键关联一段文本。所选语言存储在 Cookie 中。
[ASP.NET Core] 有自己的翻译系统([IStringLocalizer] 接口和 [.resx] 资源文件)。我们改用 JSON 字典,由为此编写的一个小类来读取:这些文件与案例研究的 [NestJS] 版本中的文件相同,其格式无需任何特殊工具即可读写。不过,我们仍让 [ASP.NET Core] 负责为每个请求选择语言:这是它的 本地化中间件的职责。
5.1. 示例 22:双语应用程序
| 22-i18n/
├── Controllers/
│ ├── LanguageController.cs
│ └── PagesController.cs
├── i18n/
│ ├── en.json
│ └── fr.json
├── Translation/
│ ├── Translator.cs
│ └── ViewPage.cs
├── Views/
│ ├── Pages/
│ │ ├── Home.cshtml
│ │ └── Products.cshtml
│ ├── Shared/
│ │ ├── _Layout.cshtml
│ │ └── _Navbar.cshtml
│ ├── _ViewImports.cshtml
│ └── _ViewStart.cshtml
├── wwwroot/
│ └── css/
│ └── styles.css
├── appsettings.json
├── Example22.csproj
└── Program.cs
|
5.1.1. 字典
文件 [i18n/fr.json]:
| {
"MENU": {
"HOME": "Accueil",
"PRODUCTS": "Produits"
},
"HOME": {
"TITLE": "Bienvenue",
"HELLO": "Bonjour {name} !",
"DATE": "Nous sommes le {date}."
},
"PRODUCTS": {
"TITLE": "Nos produits",
"NAME": "Produit",
"PRICE": "Prix",
"COUNT": "{n} produit(s) au catalogue."
}
}
|
文件 [i18n/en.json]:
| {
"MENU": {
"HOME": "Home",
"PRODUCTS": "Products"
},
"HOME": {
"TITLE": "Welcome",
"HELLO": "Hello {name}!",
"DATE": "Today is {date}."
},
"PRODUCTS": {
"TITLE": "Our products",
"NAME": "Product",
"PRICE": "Price",
"COUNT": "{n} product(s) in the catalogue."
}
}
|
- 字典是一个 JSON 文件,按页面或主题组织:键 [HOME.HELLO] refers to the text [HELLO] in section [HOME];
- 第 8 行:文本可以包含用花括号括起来的参数,翻译时会被替换。词序因语言而异:因此文本不能通过简单地拼接已翻译的片段来生成。
5.1.2. 翻译服务
文件 [Translation/Translator.cs]:
| using System.Globalization;
using System.Text.Json;
using System.Text.RegularExpressions;
namespace Example22.Translation;
// 字典,在启动时只读取一次:该服务是单例
public partial class Translator
{
public static readonly string[] Languages = ["fr", "en"];
public const string DefaultLanguage = "en";
// 语言 -> (完整键 "HOME.HELLO" -> 文本)
private readonly Dictionary<string, Dictionary<string, string>> dictionaries = [];
public Translator(IWebHostEnvironment environment)
{
foreach (var language in Languages)
{
var path = Path.Combine(environment.ContentRootPath, "i18n", $"{language}.json");
using var document = JsonDocument.Parse(File.ReadAllText(path));
var dictionary = new Dictionary<string, string>();
Flatten(document.RootElement, "", dictionary);
dictionaries[language] = dictionary;
}
}
// 当前请求的语言,由本地化中间件设置
public static string CurrentLanguage()
{
var language = CultureInfo.CurrentUICulture.TwoLetterISOLanguageName;
return Languages.Contains(language) ? language : DefaultLanguage;
}
// Translate("HOME.HELLO", { ["name"] = "Marie" }) -> "Hello Marie!"
public string Translate(string? key, IReadOnlyDictionary<string, string>? parameters = null)
{
if (string.IsNullOrEmpty(key)) return "";
// 缺失的键会显示键本身:疏漏会显示在屏幕上
var text = dictionaries[CurrentLanguage()].GetValueOrDefault(key) ?? key;
if (parameters is null) return text;
// 每个 {name} 被替换为同名参数的值
return Parameter().Replace(text, m => parameters.TryGetValue(m.Groups[1].Value, out var value) ? value : m.Value);
}
// { "MENU": { "HOME": "Home" } } -> { "MENU.HOME": "Home" }
private static void Flatten(JsonElement node, string prefix, Dictionary<string, string> result)
{
foreach (var property in node.EnumerateObject())
{
var key = prefix == "" ? property.Name : $"{prefix}.{property.Name}";
if (property.Value.ValueKind == JsonValueKind.Object)
{
Flatten(property.Value, key, result);
}
else
{
result[key] = property.Value.GetString() ?? "";
}
}
}
// 正则表达式 {name},由 C# 编译器编译
[GeneratedRegex(@"\{(\w+)\}")]
private static partial Regex Parameter();
}
|
让我们对这段代码做些说明:
- 第 8 行:关键字 [partial] 是文件末尾的正则表达式所必需的(见下文);
- 第 10–11 行:支持的语言和默认语言;
- 第 14 行:为每种语言提供一个 [C#] 字典,将每个完整的键([HOME.HELLO])与其文本关联;
- 第 16–24 行:构造函数读取 JSON 文件。[IWebHostEnvironment] 服务由 [ASP.NET Core] 提供,返回项目文件夹([ContentRootPath])。[JsonDocument.Parse] 解析 JSON 文本;[using var] 在代码块结束时释放该对象。该服务将是单例(见 [Program.cs]):文件只读取一次;
- 第 29–32 行:当前请求的语言。我们将看到,本地化中间件把它存储在 [CultureInfo.CurrentUICulture] 中。[TwoLetterISOLanguageName] 返回其两个字母的代码([fr]、[en]);
- 第 36–43 行:翻译。在当前语言的字典中查找键;如果找不到,则显示键本身:遗漏会立刻在屏幕上显现出来。正则表达式查找文本中的每个 [{name}] 参数并用其值替换;没有值的参数保持原样;
- 第 47–58 行:该函数将 JSON“展平”:对象 ["HOME": { "HELLO": "..." }] 生成键 [HOME.HELLO]。它调用自身(递归函数)来遍历嵌套对象;
- 第 64–65 行:正则表达式 [\{(\w+)\}] (一个左花括号、一个或多个单词字符(被捕获)、一个右花括号)。特性 [[GeneratedRegex]] 指示编译器在编译期间一次性生成其解析代码。该方法声明为 [partial]:其方法体由编译器生成。
5.1.3. 在视图中实现
视图可以使用 [@inject Translator Translator] 指令获取该服务,然后编写 [@Translator.Translate("MENU.HOME")]。这样做很费事,而且每个视图中都得重复一遍。我们采用另一种方式:每个 [Razor] 视图都会被编译成一个 [C#] 类,默认情况下它派生自框架的 [RazorPage<TModel>] 类。我们可以插入自己的类,为所有视图提供它们所需的方法。文件 [Translation/ViewPage.cs]:
| using System.Globalization;
using Microsoft.AspNetCore.Mvc.Razor;
using Microsoft.AspNetCore.Mvc.Razor.Internal;
namespace Example22.Translation;
// 所有视图的基类(见 Views/_ViewImports.cshtml:@inherits)
public abstract class ViewPage<TModel> : RazorPage<TModel>
{
// 通过依赖注入填充,就像在视图中使用 @inject 一样
[RazorInject]
public Translator Translator { get; set; } = null!;
// @T("HOME.HELLO", ("name", "Marie")):参数是(名称,值)对
public string T(string? key, params (string Name, object? Value)[] parameters) =>
Translator.Translate(key, parameters.ToDictionary(p => p.Name, p => p.Value?.ToString() ?? ""));
// "fr" 或 "en"
public string Language => Translator.CurrentLanguage();
// 以当前语言完整文字表示的日期
public string LongDate(DateOnly date) => date.ToString("D", CultureInfo.CurrentCulture);
// 以当前语言的格式表示的欧元金额
public string Money(decimal amount)
{
var format = (NumberFormatInfo)CultureInfo.CurrentCulture.NumberFormat.Clone();
format.CurrencySymbol = "€";
return amount.ToString("C", format);
}
}
|
让我们对这段代码做些说明:
- 第 8 行:一个泛型类——[TModel]是视图模型的类型,每个视图各不相同。该类是抽象的:只有视图继承它;
- 第 11–12 行:[[RazorInject]] 特性指示 [Razor] 通过依赖注入填充该属性:这相当于类的 [@inject] ;
- 第 15–16 行:方法 [T] 翻译一个键。它的参数是 [(name, value)] 元组:一种书写值对的紧凑语法,如 [("name", "Marie")]。关键字 [params] 允许传入任意多个,以逗号分隔。该方法将它们整理成字典交给服务。渲染出的文本是字符串:[Razor] 会对它进行转义,就像对任何 [@] 表达式一样;
- 第 19 行:当前语言,[fr] 或 [en];
- 第 22–29 行:日期和金额按当前区域性格式化,该区域性同样由本地化中间件设置(见示例 16)。
文件 [Views/_ViewImports.cshtml]:
| @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using Example22.Controllers
@using Example22.Translation
@* all the views derive from ViewPage: they have T(...), Language...;
TModel denotes the model type of each view (@model ...) *@
@inherits ViewPage<TModel>
|
- 第 6 行:指令 [@inherits] 指定视图的父类。它放在 [_ViewImports.cshtml] 中,适用于所有视图。现在每个视图都可以写 [@T("MENU.HOME")]。
5.1.4. 语言选择
文件 [Program.cs]:
| using System.Globalization;
using System.Text.Encodings.Web;
using System.Text.Unicode;
using Example22.Translation;
using Microsoft.AspNetCore.Localization;
using Microsoft.Extensions.FileProviders;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
// 字典:单个实例,在首次需要时创建
builder.Services.AddSingleton<Translator>();
var app = builder.Build();
app.UseStaticFiles();
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
RequestPath = "/bootstrap",
});
// 每个请求的语言:取 Cookie 中的语言,否则为英语
var cultures = Translator.Languages.Select(l => new CultureInfo(l)).ToList();
var localization = new RequestLocalizationOptions
{
DefaultRequestCulture = new RequestCulture(Translator.DefaultLanguage),
SupportedCultures = cultures, // 格式(日期、数字)使用的语言
SupportedUICultures = cultures, // 文本使用的语言
};
// 只有 Cookie 起决定作用(既不看浏览器语言,也不看 URL 参数)
localization.RequestCultureProviders = [new CookieRequestCultureProvider()];
app.UseRequestLocalization(localization);
app.MapControllers();
app.Run();
|
让我们分析这段代码:
- 第 12 行:翻译服务,只有单个实例;
- 第 24–29 行:本地化中间件的配置。[.NET] 区分两个概念:区域性 ([CurrentCulture]),它定义日期和数字的格式;以及界面区域性 ([CurrentUICulture]),它定义文本的语言。这里两者都被赋予同一个语言列表;不在列表中的语言会被拒绝;
- 第 32 行:到哪里查找请求的语言。默认情况下,中间件按顺序检查 URL 参数([?culture=en])、Cookie,然后是浏览器发送的 [Accept-Language] 头(即浏览器的语言)。只保留 Cookie:用户通过 FR / EN 按钮进行选择;
- 第 33 行:中间件被添加到管道中。对于每个请求,它读取 Cookie,并在请求期间设置 [CultureInfo.CurrentCulture] 和 [CultureInfo.CurrentUICulture] 。如果没有 Cookie,则默认语言为英语。
文件 [Controllers/LanguageController.cs]:
| using Example22.Translation;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
namespace Example22.Controllers;
public class LanguageController : Controller
{
// GET /language/fr:将选择存入 Cookie,然后返回上一页
[HttpGet("language/{language}")]
public IActionResult Change(string language)
{
if (!Translator.Languages.Contains(language))
{
return NotFound();
}
Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName, // Cookie 名称
CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(language)), // "c=fr|uic=fr"
new CookieOptions { MaxAge = TimeSpan.FromDays(365), SameSite = SameSiteMode.Lax, HttpOnly = true });
return Redirect(OriginPage());
}
// 我们来自的页面(Referer 标头),只保留其路径:
// 重定向到从请求中取得的完整地址
// 可能会把用户送到另一个站点(“开放重定向”漏洞)
private string OriginPage()
{
var referer = Request.Headers.Referer.ToString();
if (!Uri.TryCreate(referer, UriKind.Absolute, out var url))
{
return "/";
}
return url.PathAndQuery;
}
}
|
让我们分析这段代码:
- 第 10–21 行:[GET /language/en] 将所选语言存入一个有效期为一年的 Cookie,然后重定向到用户来自的页面。未知的语言会导致 404 错误;
- 第 17–20 行:[Response.Cookies.Append(name, value, options)] 设置一个 Cookie:浏览器会在之后的每个请求中将其发回。其名称和值的格式正是本地化中间件所期望的:我们从 [CookieRequestCultureProvider] 类中获取它们,而不必自己编写。选项:[MaxAge] (生存期)、[HttpOnly](页面的 [JavaScript] 无法读取它)、[SameSite = Lax] (来自其他站点的 POST 请求不会发送它);
- 第 27–34 行:原始页面由 [Referer] 头指定,浏览器在点击链接时会添加该头。我们只保留路径和参数([PathAndQuery]):如果重定向到请求中的完整 URL,恶意站点就可以制作一个链接,用户经过我们的站点之后会被送到该恶意站点(这种漏洞称为 [open redirect])。
5.1.5. 视图
文件 [Views/Shared/_Layout.cshtml]:
| <!doctype html>
<html lang="@Language">
<head>
<meta charset="utf-8">
@* the title is a KEY, set by the view, translated by the layout *@
<title>@T(ViewData["Title"] as string)</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-3">
<partial name="_Navbar" />
@RenderBody()
</div>
</body>
</html>
|
- 第 2 行:页面的 [lang] 特性反映所选语言(对屏幕阅读器和拼写检查器有用);
- 第 6 行:页面标题是一个键,由视图存入 [ViewData],并由模板翻译。[as string] 将该值(类型为 [object])转换为字符串,如果它不是字符串则转换为 [null] 。
文件 [Views/Shared/_Navbar.cshtml]:
| <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<div class="navbar-nav me-auto">
<a class="nav-link" href="/">@T("MENU.HOME")</a>
<a class="nav-link" href="/products">@T("MENU.PRODUCTS")</a>
</div>
@* the current language is highlighted *@
<div class="btn-group btn-group-sm">
<a class="btn @(Language == "fr" ? "btn-primary" : "btn-outline-primary")" href="/language/fr">FR</a>
<a class="btn @(Language == "en" ? "btn-primary" : "btn-outline-primary")" href="/language/en">EN</a>
</div>
</nav>
|
- 第 8–9 行:两个链接(更改语言不会修改任何应用程序数据:GET 就足够了),当前语言高亮显示。
文件 [Views/Pages/Home.cshtml]:
| @model HomeModel
@{
ViewData["Title"] = "HOME.TITLE";
}
<h1>@T("HOME.TITLE")</h1>
<p>@T("HOME.HELLO", ("name", Model.Name))</p>
<p>@T("HOME.DATE", ("date", LongDate(Model.Today)))</p>
|
- 第 6 行:一个参数,以元组形式传入;
- 第 7 行:日期先由 [LongDate] 格式化,然后作为参数 [date] 传给 [T]。
文件 [Views/Pages/Products.cshtml]:
| @model List<Product>
@{
ViewData["Title"] = "PRODUCTS.TITLE";
}
<h1>@T("PRODUCTS.TITLE")</h1>
<table class="table table-sm w-auto">
<thead><tr><th>@T("PRODUCTS.NAME")</th><th class="text-end">@T("PRODUCTS.PRICE")</th></tr></thead>
<tbody>
@foreach (var product in Model)
{
<tr><td>@product.Name</td><td class="text-end">@Money(product.Price)</td></tr>
}
</tbody>
</table>
<p>@T("PRODUCTS.COUNT", ("n", Model.Count))</p>
|
- 第 11 行:金额,按语言格式化;
- 第 15 行:一个数值参数;[T] 将其转换为字符串。
文件 [Controllers/PagesController.cs]:
| using Microsoft.AspNetCore.Mvc;
namespace Example22.Controllers;
public record Product(string Name, decimal Price);
public record HomeModel(string Name, DateOnly Today);
public class PagesController : Controller
{
[HttpGet("/")]
public IActionResult Home()
{
return View(new HomeModel("Marie", new DateOnly(2026, 9, 23)));
}
[HttpGet("products")]
public IActionResult Products()
{
List<Product> products =
[
new Product("Keyboard", 25m),
new Product("Mouse", 12.5m),
new Product("Screen", 1149m),
];
return View(products);
}
}
|
操作与语言无关:它们提供数据,由视图翻译并格式化数据。
5.1.6. 执行
英语(尚无 Cookie),URL 为 http://localhost:5000/ 和 http://localhost:5000/products:


点击 FR,用 [curl] 模拟(选项 [-H] 添加浏览器本应发送的 [Referer] 头):
| curl -i -H "Referer: http://localhost:5000/products" http://localhost:5000/language/fr
|
| HTTP/1.1 302 Found
Content-Length: 0
Location: /products
Set-Cookie: .AspNetCore.Culture=c%3Dfr%7Cuic%3Dfr; max-age=31536000; path=/; samesite=lax; httponly
|
服务器设置 [.AspNetCore.Culture] Cookie,其编码后的值为 [c=fr|uic=fr] (区域性和界面区域性),并重定向到原始页面,此时已是法语:


不受支持的语言:
| curl -i http://localhost:5000/language/de
|
| HTTP/1.1 404 Not Found
Content-Length: 0
|
案例研究正是这样进行的,只是使用了更完整的字典([i18n/fr.json] 和 [i18n/en.json]):同样的服务([Translator])、同样的父视图类(多了几个属性)、同样的控制器([/language/{language}])、同样的 Cookie。只有一处不同:业务层和 Web 层生成的错误消息也是键,由视图在最后一刻翻译。