mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-21 08:32:21 +08:00
chinboy
3018239197
- Add Overview.md: design goals, system architecture diagram, core concepts, source file inventory - Add Architecture.md: core types, Source Generator pipeline, end-to-end Dialog example, resource lifecycle, runtime language switching - Add DeveloperGuide.md: step-by-step tutorial with QRCode example, Common shared resources, Dialog/Tour/Pagination examples, application-level i18n, runtime switching API, FAQ - Update .gitignore: add .referenceprojects/ ignore rule - Bump version to 5.2.0-build.3
144 lines
9.2 KiB
Markdown
144 lines
9.2 KiB
Markdown
# AtomUI 多语言系统概览
|
|
|
|
> 本文档描述 AtomUI 国际化（i18n）系统的整体架构，包括设计目标、核心概念、系统分层以及源文件清单。
|
|
|
|
---
|
|
|
|
## 1. 设计目标
|
|
|
|
AtomUI 多语言系统遵循以下设计原则：
|
|
|
|
1. **所有用户可见文本必须通过多语言系统管理** — 禁止在控件中硬编码字符串。
|
|
2. **运行时热切换** — 用户可在运行时切换语言，UI 即时响应刷新，无需重启应用。
|
|
3. **Source Generator 自动化** — 通过 Roslyn Source Generator 自动生成资源枚举键和 XAML 标记扩展，消除手动维护的负担。
|
|
4. **与 Avalonia 资源系统深度集成** — 多语言文本以 `ResourceDictionary` 形式注入 Avalonia 资源树，利用 `DynamicResource` 机制实现动态绑定。
|
|
5. **按组件分组管理** — 每个控件的语言资源独立定义，通过 `LangId` 分组，避免全局命名冲突。
|
|
6. **可扩展** — 第三方开发者可使用相同机制为自定义控件添加多语言支持。
|
|
|
|
---
|
|
|
|
## 2. 系统架构总览
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────────────┐
|
|
│ 构建时 (Build Time) — Roslyn Source Generator │
|
|
│ │
|
|
│ LanguageGenerator (IIncrementalGenerator) │
|
|
│ ├── LanguageProviderWalker → 扫描 [LanguageProvider] 类 │
|
|
│ ├── LangResourceKeyClassSourceWriter │
|
|
│ │ → 生成 {LangId}LangResourceKind 枚举 │
|
|
│ │ → 生成 {LangId}LangResourceExtension 标记扩展 │
|
|
│ └── LanguageProviderPoolClassSourceWriter │
|
|
│ → 生成 LanguageProviderPool.GetLanguageProviders() │
|
|
└──────────────────────────────┬───────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────────────────────────────────────┐
|
|
│ 应用初始化 (App Init) │
|
|
│ │
|
|
│ Application.UseAtomUI(builder => { │
|
|
│ builder.WithDefaultLanguageVariant(LanguageVariant.zh_CN); │
|
|
│ builder.UseDesktopControls(); // 注册 LanguageProviderPool │
|
|
│ }) │
|
|
│ │ │
|
|
│ ├── ThemeManagerBuilder 收集所有 LanguageProvider │
|
|
│ ├── ThemeManagerBuilder.Build() → 创建 ThemeManager │
|
|
│ ├── ThemeManager.Configure() → BuildLanguageResources() │
|
|
│ │ └── 按 LanguageVariant 分组，构建 ResourceDictionary │
|
|
│ └── 设置初始 LanguageVariant → 对应语言 ResourceDictionary │
|
|
│ 注入 MergedDictionaries │
|
|
└──────────────────────────────┬───────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────────────────────────────────────┐
|
|
│ 运行时 (Runtime) │
|
|
│ │
|
|
│ AXAML 主题中使用 {atom:XxxLangResource Key} 绑定语言文本 │
|
|
│ │
|
|
│ 运行时切换语言： │
|
|
│ application.SetLanguageVariant(LanguageVariant.en_US) │
|
|
│ │ │
|
|
│ └── ThemeManager.LanguageVariant 属性变更 │
|
|
│ ├── 移除旧语言 ResourceDictionary │
|
|
│ ├── 注入新语言 ResourceDictionary │
|
|
│ └── 触发 LanguageVariantChanged 事件 │
|
|
│ → DynamicResource 自动刷新所有绑定控件 │
|
|
└──────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 核心概念
|
|
|
|
| 概念 | 说明 |
|
|
|------|------|
|
|
| **LanguageCode** | 语言代码枚举，如 `zh_CN`、`en_US` |
|
|
| **LanguageVariant** | 语言变体的类型安全封装，支持与 `CultureInfo` 互转 |
|
|
| **LanguageProvider** | 单个语言+单个组件的文本定义类，包含所有 `public const string` 字段 |
|
|
| **LangId** | 语言资源分组标识（通常与控件 Token ID 一致），同一 `LangId` 下不同语言共享同一组资源键 |
|
|
| **LangResourceKind** | Source Generator 自动生成的资源键枚举，作为 `ResourceDictionary` 的键 |
|
|
| **LangResourceExtension** | Source Generator 自动生成的 XAML 标记扩展，在 AXAML 中绑定语言文本 |
|
|
| **LanguageProviderPool** | Source Generator 自动生成的工厂类，列举当前程序集中所有 `LanguageProvider` |
|
|
| **CommonLangId** | 跨控件共享的通用语言分组，如 "确定"、"取消"、"提交" 等 |
|
|
|
|
---
|
|
|
|
## 4. 源文件清单
|
|
|
|
### 4.1 核心基础设施 (`src/AtomUI.Core/Language/`)
|
|
|
|
| 文件 | 职责 |
|
|
|------|------|
|
|
| `LanguageCode.cs` | `LanguageCode` 枚举定义（`zh_CN`、`en_US`），含 `ToHyphenString()` 扩展方法 |
|
|
| `LanguageVariant.cs` | `LanguageVariant` record — 语言变体的类型安全封装，含 `StyledProperty`、`CultureInfo` 互转 |
|
|
| `LanguageVariantTypeConverter.cs` | XAML 字符串到 `LanguageVariant` 的类型转换器 |
|
|
| `LanguageVariantChangedEventArgs.cs` | 语言切换事件参数 |
|
|
| `ILanguageProvider.cs` | 语言提供者接口 — `LangCode`、`LangId`、`BuildResourceDictionary()` |
|
|
| `LanguageProvider.cs` | 语言提供者抽象基类 — 通过反射将 `const string` 字段写入 `ResourceDictionary` |
|
|
| `LanguageProviderAttribute.cs` | `[LanguageProvider]` 标注 — 指定语言代码和分组 ID |
|
|
| `LanguageSgMetaInfoAttribute.cs` | `[assembly: LanguageSgMetaInfo]` — 指定 Source Generator 输出命名空间 |
|
|
| `LanguageResourceExtension.cs` | `LanguageResourceExtension<T>` 泛型 XAML 标记扩展基类 |
|
|
| `CommonLangId.cs` | `CommonLangId.Common` — 跨控件通用语言分组常量 |
|
|
|
|
### 4.2 Source Generator (`src/AtomUI.Generator/Language/`)
|
|
|
|
| 文件 | 职责 |
|
|
|------|------|
|
|
| `LanguageInfo.cs` | 数据模型 — 存储单个 LanguageProvider 类的解析结果 |
|
|
| `LanguageProviderWalker.cs` | Roslyn Syntax Walker — 遍历 `[LanguageProvider]` 类，提取字段和元信息 |
|
|
| `LangResourceKeyClassSourceWriter.cs` | 代码生成器 — 输出 `{LangId}LangResourceKind` 枚举 + `{LangId}LangResourceExtension` 标记扩展 |
|
|
| `LanguageProviderPoolClassSourceWriter.cs` | 代码生成器 — 输出 `LanguageProviderPool.GetLanguageProviders()` 工厂方法 |
|
|
|
|
Source Generator 入口：`src/AtomUI.Generator/LanguageGenerator.cs`
|
|
|
|
### 4.3 运行时集成
|
|
|
|
| 文件 | 职责 |
|
|
|------|------|
|
|
| `src/AtomUI.Core/Theme/ThemeManager.cs` | 管理 `_languages` 字典，处理语言切换的 `ResourceDictionary` 替换 |
|
|
| `src/AtomUI.Core/Theme/ThemeManagerBuilder.cs` | 收集 `LanguageProvider` 实例，构建 `ThemeManager` |
|
|
| `src/AtomUI.Core/Theme/IThemeManager.cs` | 公开 `LanguageVariant` 属性和 `LanguageVariantChanged` 事件 |
|
|
| `src/AtomUI.Core/ApplicationExtensions.cs` | `UseAtomUI()` 入口 — 设置默认语言并初始化 |
|
|
| `src/AtomUI.Controls.Shared/ApplicationExtensions.cs` | `SetLanguageVariant()` / `GetLanguageVariant()` 便捷扩展方法 |
|
|
|
|
---
|
|
|
|
## 5. 当前支持的语言
|
|
|
|
| LanguageCode | LanguageVariant | 显示名称 | CultureInfo |
|
|
|---|---|---|---|
|
|
| `zh_CN` | `LanguageVariant.zh_CN` | 简体中文 | `zh-CN` |
|
|
| `en_US` | `LanguageVariant.en_US` | English | `en-US` |
|
|
|
|
默认语言为 `en_US`（在 `ApplicationExtensions.UseAtomUI()` 中设置），但 Gallery 示例应用使用 `zh_CN` 作为默认语言。
|
|
|
|
---
|
|
|
|
## 6. 相关文档
|
|
|
|
| 文档 | 内容 |
|
|
|------|------|
|
|
| [Architecture.md](./Architecture.md) | 多语言系统内部架构详解 — 核心类型、Source Generator 管线、资源生命周期 |
|
|
| [DeveloperGuide.md](./DeveloperGuide.md) | 开发者使用指南 — 如何为自定义控件添加多语言支持（含完整示例） |
|
|
|