Ant Design Blazor 本地化方案详解

Ant Design Blazor 本地化方案详解

ant-design-blazor 🌈A set of enterprise-class UI components based on Ant Design and Blazor WebAssembly. 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-blazor

前言

在当今全球化应用开发中，多语言支持已成为必备功能。Ant Design Blazor 作为一款优秀的企业级 Blazor UI 组件库，提供了完善的本地化解决方案。本文将深入解析 Ant Design Blazor 的本地化实现机制，帮助开发者快速掌握多语言应用的开发技巧。

本地化方案概述

Ant Design Blazor 提供了两种主要的本地化实现方式：

1. 基于 .NET 标准本地化方案：使用 IStringLocalizer 接口和资源文件（.resx）
2. 简单 JSON 提供者方案：使用 JSON 文件存储多语言内容

两种方案各有特点，开发者可根据项目需求选择适合的方式。

标准本地化方案实现

1. 安装与配置

首先需要安装本地化扩展包：

dotnet add package AntDesign.Extensions.Localization

然后在 Program.cs 中进行配置：

builder.Services.AddInteractiveStringLocalizer();
services.AddLocalization(options =>
{
    options.ResourcesPath = "Resources";
});

2. 资源文件创建

在项目的 Resources 目录下创建资源文件，命名格式为 {ResourceName}.{culture}.resx。例如：

• Index.en-US.resx（英文资源）
• Index.zh-CN.resx（中文资源）

每个资源文件包含键值对，如：

| 键 (Name) | 值 (Value) | |----------|-----------| | Hello | 你好 | | Goodbye | 再见 |

3. 资源文件自动生成

为确保资源文件能被正确识别，需要在项目文件中添加配置：

<ItemGroup>
    <Compile Update="Resources\Resources.Designer.cs">
        <DesignTime>True</DesignTime>
        <AutoGen>True</AutoGen>
        <DependentUpon>Resources.resx</DependentUpon>
    </Compile>
</ItemGroup>

<ItemGroup>
    <EmbeddedResource Update="Resources\Resources.resx">
        <Generator>PublicResXFileCodeGenerator</Generator>
        <LastGenOutput>Resources.Designer.cs</LastGenOutput>
    </EmbeddedResource>
</ItemGroup>

4. 在组件中使用

在 Razor 组件中注入 IStringLocalizer<T> 服务：

@inject IStringLocalizer<Index> localizer

<p>@localizer["Hello"]</p>
<p>@localizer["Goodbye"]</p>

5. 动态语言切换

实现语言切换功能需要订阅语言变更事件：

@implements IDisposable
@inject ILocalizationService LocalizationService

<Button OnClick="()=>LocalizationService.SetLanguage("en-US")">English</Button>
<Button OnClick="()=>LocalizationService.SetLanguage("zh-CN")">中文</Button>

@code {
    protected override void OnInitialized()
    {
        LocalizationService.LanguageChanged += OnLanguageChanged;
    }
    
    private void OnLanguageChanged(object sender, CultureInfo args)
    {
        InvokeAsync(StateHasChanged);
    }
    
    public void Dispose()
    {
        LocalizationService.LanguageChanged -= OnLanguageChanged;
    }
}

表单验证本地化

Ant Design Blazor 的表单组件默认使用 ObjectGraphDataAnnotationsValidator 进行验证，支持 DataAnnotations 的本地化。例如：

public class Model
{
    [Required(ErrorMessage = "用户名是必填项")]
    [Display(Name = "用户名")]
    public string Username { get; set; }
}

验证消息可以通过资源文件进行本地化。

DisplayAttribute 本地化支持

多个组件（如 FormItem、EnumSelect 等）支持通过 DisplayAttribute 特性实现标签本地化：

public class Model
{
    [Display(Name = nameof(Resources.App.UserName), ResourceType = typeof(Resources.App))]
    public string Username { get; set; }
}

public enum Province
{
    [Display(Name = nameof(Resources.App.Shanghai), ResourceType = typeof(Resources.App))]
    Shanghai,
    Jiangsu
}

简单 JSON 提供者方案

对于小型项目，可以使用更简单的 JSON 本地化方案：

1. 配置服务

builder.Services.AddSimpleEmbeddedJsonLocalization(options =>
{
    options.ResourcesPath = "Resources";
    options.Resources = SimpleStringLocalizerOptions.BuildResources("Resources", Assembly.GetExecutingAssembly());
});

2. 创建 JSON 文件

在 Resources 目录下创建 {culture}.json 文件：

// en-US.json
{
    "Hello": "Hello!",
    "Goodbye": "Goodbye!"
}

// zh-CN.json
{
    "Hello": "你好!",
    "Goodbye": "再见!"
}

3. 配置项目文件

确保 JSON 文件被嵌入为资源：

<ItemGroup>
    <EmbeddedResource Include="Resources\*.json" />
</ItemGroup>

4. 在组件中使用

@inject IStringLocalizer localizer

<p>@localizer["Hello"]</p>
<p>@localizer["Goodbye"]</p>

路由语言标识实现

实现基于路由的语言标识可以提升用户体验和 SEO 效果。核心实现包括：

1. 在路由组件中处理语言切换
2. 为页面组件添加 {locale} 参数

路由组件实现

@inject ILocalizationService LocalizationService
@inject NavigationManager NavigationManager

<Router AppAssembly="typeof(App).Assembly" OnNavigateAsync="OnNavigateAsync">
    <!-- 路由配置 -->
</Router>

@code {
    async Task OnNavigateAsync(NavigationContext context)
    {
        var path = context.Path;
        var culture = LocalizationService.CurrentCulture;
        
        // 处理语言标识逻辑
        if (string.IsNullOrWhiteSpace(segment))
        {
            NavigationManager.NavigateTo($"{culture.Name}/{path}");
        }
        else if (segment.IsIn("zh-CN", "en-US"))
        {
            LocalizationService.SetLanguage(CultureInfo.GetCultureInfo(segment));
        }
        // 其他处理逻辑...
    }
}

页面组件实现

@page "/{locale}/Index"

@inject IStringLocalizer<Index> localizer

<p>@localizer["Hello"]</p>

@code {
    [Parameter]
    public string Locale { get; set; }
}

最佳实践建议

1. 资源文件组织：按功能模块组织资源文件，避免单一大型资源文件
2. 文化回退：设置默认文化，当请求的文化不存在时使用回退文化
3. 性能优化：对于大型应用，考虑使用延迟加载资源
4. 测试验证：全面测试各种文化下的 UI 布局，确保文本不会破坏布局

结语

Ant Design Blazor 的本地化方案提供了灵活的选择，无论是标准的 .NET 本地化方案还是简单的 JSON 方案，都能满足不同规模项目的需求。通过合理利用路由语言标识和动态切换功能，可以打造出用户体验良好的国际化应用。希望本文能帮助开发者更好地理解和应用 Ant Design Blazor 的本地化功能。

ant-design-blazor 🌈A set of enterprise-class UI components based on Ant Design and Blazor WebAssembly. 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-blazor