Skip to content

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]:

1
2
3
4
5
6
@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]:

1
2
3
4
5
6
7
@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:

Image

Image

点击 FR,用 [curl] 模拟(选项 [-H] 添加浏览器本应发送的 [Referer] 头):

curl -i -H "Referer: http://localhost:5000/products" http://localhost:5000/language/fr
1
2
3
4
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] (区域性和界面区域性),并重定向到原始页面,此时已是法语:

Image

Image

不受支持的语言:

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 层生成的错误消息也是键,由视图在最后一刻翻译。