AtomUI/docs/Gallery/05-LocalizationSystem.md

国际化系统

1. 概述

Gallery 使用 AtomUI 自研的国际化系统，基于 LanguageProvider + Source Generator 实现。支持中文（zh_CN）和英文（en_US）两种语言，运行时动态切换。

2. 架构

graph TB
    subgraph "定义层"
        LP["LanguageProvider 子类<br/>定义 const string 字段"]
        ZH["zh_CN.cs<br/>中文翻译"]
        EN["en_US.cs<br/>英文翻译"]
    end

    subgraph "生成层 (Source Generator)"
        Enum["CaseNavigationLangResourceKind<br/>自动生成枚举"]
        Ext["CaseNavigationLangResourceExtension<br/>自动生成 XAML 扩展"]
        Pool["LanguageProviderPool.g.cs<br/>自动生成注册池"]
    end

    subgraph "使用层"
        XAML["XAML 中使用<br/>{CaseNavigationLangResource DataDisplay}"]
        Code["代码中使用<br/>LanguageManager.Instance"]
    end

    LP --> Enum
    LP --> Ext
    LP --> Pool
    ZH --> LP
    EN --> LP
    Enum --> XAML
    Ext --> XAML
    Pool --> Code

3. LanguageProvider 定义模式

每个需要国际化的模块定义一个 LanguageProvider 子类：

// Workspace/Localization/CaseNavigationLang/zh_CN.cs
[LanguageProvider("CaseNavigation")]
public class CaseNavigationZhCN : AbstractLanguageProvider
{
    public const string General = "通用";
    public const string General_Button = "按钮 Button";
    public const string DataDisplay = "数据展示";
    // ...
}

// Workspace/Localization/CaseNavigationLang/en_US.cs
[LanguageProvider("CaseNavigation")]
public class CaseNavigationEnUS : AbstractLanguageProvider
{
    public const string General = "General";
    public const string General_Button = "Button";
    public const string DataDisplay = "Data Display";
    // ...
}

关键规则

1. [LanguageProvider("Name")] — 标记类为语言提供者，参数为提供者名称
2. 同一名称的多个类 — 对应不同语言变体（zh_CN / en_US）
3. const string 字段 — 字段名作为资源键，字段值作为翻译文本
4. 字段名必须一致 — 不同语言类中相同含义的字段名必须完全相同

4. Source Generator 生成内容

4.1 LanguageResourceConst.g.cs

自动生成枚举和 XAML 扩展标记：

// 自动生成
public enum CaseNavigationLangResourceKind
{
    DataDisplay,
    DataDisplay_Avatar,
    DataDisplay_Badge,
    // ... 所有 const string 字段名
    General,
    General_Button,
    // ...
}

public class CaseNavigationLangResourceExtension : LanguageResourceExtension<CaseNavigationLangResourceKind>
{
    // XAML 标记扩展，用于在 XAML 中引用国际化文本
}

4.2 LanguageProviderPool.g.cs

自动生成语言提供者注册池，在应用启动时自动注册所有语言提供者。

5. XAML 中使用

<!-- 使用生成的 XAML 扩展 -->
<NavMenuItem Header="{CaseNavigationLangResource General_Button}" 
             ItemKey="{x:Static vm:ButtonViewModel.ID}"/>

6. 语言切换

通过 Application.Current.SetLanguageVariant() 切换语言：

// 切换到中文
Application.Current.SetLanguageVariant(LanguageVariant.zh_CN);

// 切换到英文
Application.Current.SetLanguageVariant(LanguageVariant.en_US);

切换后，所有使用 LanguageResourceExtension 的绑定会自动更新。

7. 当前国际化模块

模块	LanguageProvider 名称	文件位置
导航面板	CaseNavigation	Workspace/Localization/CaseNavigationLang/
窗口菜单	WorkspaceWindow	Workspace/Localization/WorkspaceWindowLang/

8. 新增国际化资源步骤

1. 在对应模块的 Localization/ 目录下创建 zh_CN.cs 和 en_US.cs
2. 两个文件中定义相同名称的 const string 字段
3. 使用 [LanguageProvider("ModuleName")] 标记类
4. Source Generator 自动生成枚举和 XAML 扩展
5. 在 XAML 中使用 {ModuleNameLangResource FieldName} 引用

9. WorkspaceWindowLang 资源清单

资源键	中文	英文
MenuItemCompactMode	紧凑模式	Compact Mode
MenuItemDarkMode	暗色模式	Dark Mode
MenuItemEnableFullScreen	允许全屏	Enable Full Screen
MenuItemEnableMaximize	允许最大化	Enable Maximize
MenuItemEnableMinimize	允许最小化	Enable Minimize
MenuItemEnableMotion	启用动效	Enable Motion
MenuItemEnableMove	允许移动	Enable Move
MenuItemEnablePin	允许置顶	Enable Pin
MenuItemEnableResize	允许调整大小	Enable Resize
MenuItemEnableWaveSpirit	启用波纹	Enable Wave Spirit
MenuItemLanguage	语言	Language
MenuItemSettings	设置	Settings
MenuItemTheme	主题	Theme
MenuItemWindowOptions	窗口选项	Window Options