在 Blazor 应用中实现国际化与多语言支持：告别繁琐的 Resx

在开发全球化 Web 应用时，多语言支持（I18n）是不可或缺的。微软原生的本地化方案通常依赖 .resx 资源文件，但其编辑体验较差且不支持动态加载。今天介绍一个更符合现代化开发习惯的库：Toolbelt.Blazor.I18nText。

1. 为什么选择 Toolbelt.Blazor.I18nText？#

传统的 .resx 方案在 Blazor 中略显笨重，而该库提供了以下优势：

格式友好：支持使用 JSON 或 CSV 存储翻译文本。
强类型支持：在编译阶段自动生成 C# 类，提供智能提示，避免拼写错误。
动态切换：无需刷新页面即可实时切换语言。
轻量化：完美适配 Blazor WebAssembly (WASM) 和 Blazor Server。

2. 环境搭建与依赖安装#

首先，创建一个 Blazor 项目并集成该库：

1
# 创建项目
2
dotnet new blazorserver -o MyI18nApp
3
# 安装 Toolbelt.Blazor.I18nText
4
dotnet add MyI18nApp package Toolbelt.Blazor.I18nText

在 Program.cs 中注册服务：

1
using Toolbelt.Blazor.Extensions.DependencyInjection; // 别忘了引用
2

3
var builder = WebApplication.CreateBuilder(args);
4
// ...
5
builder.Services.AddI18nText(); // 注入 I18nText 服务

3. 创建本地化源文件#

该库的精髓在于：你只需要创建 JSON 文件，它会在构建时自动为你生成 C# 代码。

在项目中创建一个 i18ntext 文件夹（建议统一存放），创建以下文件：

中文 (MyText.zh.json):

1
{
2
   "Title": "仪表盘",
3
   "HelloWorld": "世界你好!",
4
   "BarCode": "条码",
5
   "UnitPrice": "价格",
6
   "Save": "保存"
7
}

英文 (MyText.en.json):

1
{
2
   "Title": "Dashboard",
3
   "HelloWorld": "Hello, World!",
4
   "BarCode": "BarCode",
5
   "UnitPrice": "Price",
6
   "Save": "Save"
7
}

💡 重要提示：在你运行 dotnet build 后，该库会扫描这些 JSON 文件并自动在 i18ntext 命名空间下生成 MyText 类。这样你就可以在代码中通过 MyText.Title 这种强类型方式访问，而不是字符串硬编码。

4. 在页面中实战应用#

利用强类型对象和注入服务，我们可以非常优雅地实现多语言：

1
@page "/"
2
@using MyI18nApp.I18nText @* 引用自动生成的命名空间 *@
3
@inject Toolbelt.Blazor.I18nText.I18nText I18nText
4

5
<PageTitle>@MyTextData.Title</PageTitle>
6

7
<div class="container">
8
    <h1>@MyTextData.HelloWorld</h1>
9

10
    <div class="card p-3">
11
        <label>@MyTextData.BarCode: 123456789</label>
12
        <label>@MyTextData.UnitPrice: ￥99.00</label>
13
        <button class="btn btn-success">@MyTextData.Save</button>
14
    </div>
15

16
    <hr />
17

18
    <div class="btn-group">
19
        <button class="btn btn-outline-primary" @onclick='() => ChangeLang("zh")'>中文</button>
20
        <button class="btn btn-outline-primary" @onclick='() => ChangeLang("en")'>English</button>
21
    </div>
22
</div>
23

24
@code {
25
    // 实例化自动生成的强类型类
26
    MyText MyTextData = new MyText();
27

28
    protected override async Task OnInitializedAsync()
29
    {
30
        // 加载当前语言对应的文本表
31
        MyTextData = await I18nText.GetTextTableAsync<MyText>(this);
32
    }
33

34
    private async Task ChangeLang(string lang)
35
    {
36
        // 动态切换语言，组件会自动重新渲染
37
        await I18nText.SetCurrentLanguageAsync(lang);
38
    }
39
}

5. 进阶：如何处理复杂的 UI 布局？#

当语言切换时，某些语言（如德语、西班牙语）的单词长度可能远超中文或英文。

Tip 1：Flex 布局：在多语言应用中，尽量使用 Flexbox 布局以适应不确定的文本长度。
Tip 2：回退机制：如果 MyText.fr.json 缺少某个键值，该库会自动回退到默认语言文件（通常是第一个检测到的文件），确保 UI 不会出现空白。

总结#

Toolbelt.Blazor.I18nText 彻底简化了 Blazor 的国际化流程。它通过“构建时生成强类型”的思路，既保证了开发的灵活性（使用 JSON），又保留了 C# 的严谨性（类型安全）。