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

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

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

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

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

2. 环境搭建与依赖安装

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

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

在 Program.cs 中注册服务：

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

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

3. 创建本地化源文件

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

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

中文 (MyText.zh.json):

{
   "Title": "仪表盘",
   "HelloWorld": "世界你好!",
   "BarCode": "条码",
   "UnitPrice": "价格",
   "Save": "保存"
}

英文 (MyText.en.json):

{
   "Title": "Dashboard",
   "HelloWorld": "Hello, World!",
   "BarCode": "BarCode",
   "UnitPrice": "Price",
   "Save": "Save"
}

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

4. 在页面中实战应用

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

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

<PageTitle>@MyTextData.Title</PageTitle>

<div class="container">
    <h1>@MyTextData.HelloWorld</h1>
    
    <div class="card p-3">
        <label>@MyTextData.BarCode: 123456789</label>
        <label>@MyTextData.UnitPrice: ￥99.00</label>
        <button class="btn btn-success">@MyTextData.Save</button>
    </div>

    <hr />

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

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

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

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

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

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

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

总结

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