docs(Localization): separate system module and reference docs

2026-10-16 21:21:03 +08:00 · 2026-08-10 09:02:52 +08:00
parent 83ff8e94ed
commit a43ea82e4b
15 changed files with 60 additions and 36 deletions
@@ -77,7 +77,7 @@ Read the relevant document before touching the corresponding area:

 - Overall architecture: [docs/architecture/overview.md](docs/architecture/overview.md)
 - Module boundaries: [docs/architecture/dependency-graph.md](docs/architecture/dependency-graph.md)
- Localization target architecture: [docs/modules/localization/overview.md](docs/modules/localization/overview.md)
+- Localization target architecture: [docs/architecture/systems/localization/index.md](docs/architecture/systems/localization/index.md)
 - AI collaboration and bug-fix discipline: [docs/engineering/agent-guidelines.md](docs/engineering/agent-guidelines.md)
 - AOT, trimming, dynamic data, source generators: [docs/engineering/aot-programming-guidelines.md](docs/engineering/aot-programming-guidelines.md)
 - Compiler diagnostics: [docs/engineering/compiler-diagnostics-guidelines.md](docs/engineering/compiler-diagnostics-guidelines.md)
@@ -6,5 +6,6 @@
 `docs/modules/`；使用步骤和示例进入 `docs/guides/`；精确格式和协议进入 `docs/reference/`。

 - [主题系统](theming/index.md)：主题运行时、Token、Semantic Part、定制 Guide 和 XML Reference。
+- [本地化系统](localization/index.md)：运行时、Generator、Build Tasks、语言包和 XLIFF Reference。

-本地化、Control 基础设施、渲染和窗口系统在对应文档完成迁移后继续从本入口统一导航。
+Control 基础设施、渲染和窗口系统在对应文档完成迁移后继续从本入口统一导航。
@@ -1,7 +1,7 @@
 # 本地化生成与构建架构

 本文定义 `AtomUI.Generator`、`AtomUI.Build.Tasks` 和 MSBuild targets 如何把 Catalog/XLIFF 转换为 AOT 友好的
-运行时代码。运行时设计见 [runtime-architecture.md](runtime-architecture.md)，语言包协议见
+运行时代码。运行时设计见 [runtime.md](runtime.md)，语言包协议见
 [language-packs.md](language-packs.md)。

 ## 构建链总览
@@ -24,23 +24,6 @@ MSBuild 负责发现文件、项目引用桥接、AdditionalFiles metadata 投
 静态语言包项目不生成运行时代码，因此仍由 `PrepareLanguagePackageTask` 在 pack 前完整校验。两条路径共享中立的
 XLIFF 解析与文件级校验模型，但普通应用和模块编译不再运行重复的 MSBuild XLIFF 语义校验 Task。

-## 与重构前方案的比较
-
-| 维度 | 重构前方案 | Generator 优先方案 | 结论 |
-|---|---|---|---|
-| 编译语义权威 | MSBuild Task 与 Generator 都校验一部分 XLIFF/Catalog 规则，边界重叠 | Generator 独占编译项目中的 Catalog/Bundle 语义；Build Tasks 独占静态包产物和副作用 | 消除重复规则和诊断漂移，采用新方案 |
-| props/targets | 同时承载默认值、校验策略、Task 调度、输入投影、项目桥接和 pack 行为 | props 只保留稳定默认值/item 定义；targets 只负责发现、最小 metadata 投影、项目桥接和 pack/export | MSBuild 文件更短，职责可审计，采用新方案 |
-| Generator 内部复杂度 | 表面上类型较少，但解析、引用解析、冲突处理和输出容易集中到 `LanguageCatalogCompiler` | 使用 parser、metadata validator、symbol index、planner、semantic validator、Bundle compiler、plan 和 emitter 明确分责 | 增加的是可测试的结构化复杂度，不是缺点；禁止重新形成巨型 Compiler |
-| 第三方语言包 | 作者期组件契约与消费期组件可见性容易混成一个状态，缺少组件时的行为不够清楚 | `Verified`/`Deferred` 与 `Active`/`Dormant` 正交；允许社区包独立发布，并在实际激活时恢复严格校验 | 新方案覆盖真实第三方制作和可选组件场景 |
-| 诊断体验 | 同一根因可能先由 MSBuild、后由 Generator 以不同位置或消息重复报告 | 编译输入由 Generator 提供带 AdditionalText 位置的统一诊断；静态包 build/pack 由 Prepare task 报告 | 诊断来源与修复入口更明确 |
-| 增量与性能 | 普通编译可能先由 Task 扫描/解析，再由 Generator 再次解析和绑定 | Generator 增量输入只解析一次，并为当前及引用 Catalog 建立一次 `CatalogSymbolIndex` | 减少重复工作，但必须用增量失效和确定性测试保护 |
-| 静态语言包安全 | 通用编译校验 Task 与 pack 规则交织 | `PrepareLanguagePackageTask` 继续完整执行 final 门禁、manifest/props、路径和包内容安全 | 新方案没有削弱 pack 安全边界 |
-| 兼容性 | 现有属性、metadata 和 target 顺序继续累积历史负担 | 允许删除或重命名旧内部构建契约，只保留新的最小协议 | 本次重构明确不承担旧构建契约兼容成本 |
-
-新方案的核心不是把 XML 中的分支逐行翻译到一个 C# 类，而是把语义建立为不可变输入、一次性索引、显式规划、
-独立校验、编译计划和纯输出的流水线。文件和类型数量会适度增加，但规则所有权、测试边界和增量依赖同时变得清晰；
-这属于必要的架构组织。真正需要防止的是职责重新集中、阶段互相回查原始输入，或 Writer 再次实现语义规则。
-
 ## MSBuild items

 `AtomUI.Localization.targets` 自动收集标准目录中的 XLIFF，并排除 `bin/`、`obj/` 和生成目录：
@@ -1,11 +1,8 @@
-# AtomUI 多语言模块架构概览
+# AtomUI 本地化系统架构

-本文档集是 AtomUI 多语言模块的正式架构与长期维护规范。实现、重构计划和带日期的设计记录都必须以本目录为准。
-该模块是面向整个应用的本地化基础设施，不只服务控件；语言状态、Catalog、编译期翻译表和 Avalonia 资源桥由
-`AtomUI.Localization` 拥有，主题系统不再承担语言职责。
-
-`docs/superpowers/specs/` 和 `docs/superpowers/plans/` 下的带日期文档只记录一次重构的决策过程与执行步骤，用于补充说明
-本目录中的正式架构，不能替代、覆盖或成为多语言设计的事实来源。若两者出现差异，必须先更新本目录并以本目录为准。
+本地化系统是面向整个应用的跨模块基础设施，不只服务 Control。它由 `AtomUI.Localization` 运行时、
+`AtomUI.Generator`、`AtomUI.Build.Tasks`、静态语言包和应用构建入口共同组成；语言状态、Catalog、编译后翻译表和
+Avalonia 资源桥与主题系统保持独立。

 ## 设计目标

@@ -22,17 +19,17 @@

 | 文档 | 所有权 |
 |---|---|
-| [public-api.md](public-api.md) | 启动配置、`LanguageTag`、`ILanguageManager`、`ILocalizer`、XAML 与 C# 使用面 |
-| [catalog-and-xliff.md](catalog-and-xliff.md) | Language Catalog 契约、目录约定、XLIFF 2.1、稳定 Key、格式化与覆盖规则 |
-| [runtime-architecture.md](runtime-architecture.md) | Registry、Snapshot、Manager、ResourceProvider、切换、回退、Culture 和 RTL |
+| [公共 API](../../../reference/localization/public-api.md) | 启动配置、`LanguageTag`、`ILanguageManager`、`ILocalizer`、XAML 与 C# 使用面 |
+| [Catalog 与 XLIFF](../../../reference/localization/catalog-and-xliff.md) | Language Catalog 契约、目录约定、XLIFF 2.1、稳定 Key、格式化与覆盖规则 |
+| [runtime.md](runtime.md) | Registry、Snapshot、Manager、ResourceProvider、切换、回退、Culture 和 RTL |
 | [generation-and-build.md](generation-and-build.md) | Source Generator、应用 bootstrap、AdditionalFiles、`AtomUI.Build.Tasks` 与 NuGet 布局 |
 | [language-packs.md](language-packs.md) | 内置语言、官方聚合包、模块包、第三方语言包、模板和消费协议 |
-| [diagnostics-and-testing.md](diagnostics-and-testing.md) | 构建诊断、运行时不变量、Generator/Task/集成/AOT 验证要求 |
-| [migration.md](migration.md) | 已完成重构的历史映射、兼容结果和旧 API 删除清单 |
+| [verification.md](verification.md) | 构建诊断、运行时不变量、Generator/Task/集成/AOT 验证要求 |
+| [AtomUI.Localization 模块](../../../modules/localization/index.md) | 运行时项目的源码职责、入口和依赖关系 |

 ## 项目边界

-目标源码和发布边界如下：
+源码和发布边界如下：

 | 项目或包 | 职责 | 运行时依赖 |
 |---|---|---|
@@ -1,7 +1,7 @@
 # 本地化诊断与验证规范

 本文定义多语言模块如何把错误放在正确阶段暴露，以及实现和发布必须具备的测试证据。诊断 ID 的具体注册仍
-遵守 [AtomUI 编译期诊断规范](../../engineering/compiler-diagnostics-guidelines.md)。
+遵守 [AtomUI 编译期诊断规范](../../../engineering/compiler-diagnostics-guidelines.md)。

 ## 诊断所有权

@@ -45,7 +45,7 @@ registry 后不扫描上层程序集或 AXAML。它对多个上层项目开放 `

 - [主题系统架构](../../architecture/systems/theming/runtime.md)
 - [Semantic Part 系统设计](../../architecture/systems/theming/semantic-parts.md)
- [AtomUI 多语言模块架构](../localization/overview.md)
+- [AtomUI 本地化系统架构](../../architecture/systems/localization/index.md)
 - [主题定制指南](../../guides/theming/customization.md)
 - [主题定义 XML v1 规范](../../reference/theming/theme-definition-xml-v1.md)
 - [AtomUI Theme Definition XML Schema v1](../../reference/theming/schemas/atomui-theme-v1.xsd)
@@ -0,0 +1,37 @@
+# AtomUI.Localization 模块
+
+`AtomUI.Localization` 是 AtomUI 的应用级本地化运行时项目。它提供语言身份、Catalog registry、不可变 Snapshot、
+LanguageManager、Localizer 和 Avalonia 动态资源桥，不拥有 XLIFF 构建、语言包打包或主题状态。
+
+## 职责
+
+- 定义 `LanguageTag`、`LanguageDefinition`、`LanguageState` 和 `LanguageSnapshot`。
+- 注册编译期生成的 Catalog 与 Translation Bundle descriptor。
+- 构建并原子发布当前语言的完整资源快照。
+- 提供 `ILanguageManager`、`ILocalizer` 和 XAML 资源扩展运行时。
+- 管理 Culture、FlowDirection、回退和资源 Provider 生命周期。
+
+## 源码目录
+
+| 目录 | 职责 |
+| --- | --- |
+| `Catalog/` | Catalog schema、descriptor 和 registry |
+| `Resources/` | Avalonia resource extension、provider 和 resource key |
+| `Services/` | bootstrap、builder、host、manager、localizer 和日志入口 |
+| `LanguageData/` | LanguageTags Generator 的固定数据输入 |
+| 项目根目录 | language identity、definition、state、snapshot 和回退模型 |
+
+## 对外关系
+
+- `AtomUI.Core` 引用本模块并在根 Builder 中暴露本地化配置入口。
+- `AtomUI.Generator` 生成 Catalog、Bundle、模块注册和应用 bootstrap。
+- `AtomUI.Build.Tasks` 负责静态语言包文件与打包副作用。
+- Control 包只注册自身 Catalog 和内置 Bundle，不实现独立语言状态。
+
+## 相关文档
+
+- [本地化系统架构](../../architecture/systems/localization/index.md)
+- [本地化运行时架构](../../architecture/systems/localization/runtime.md)
+- [本地化生成与构建](../../architecture/systems/localization/generation-and-build.md)
+- [公共 API](../../reference/localization/public-api.md)
+- [Catalog 与 XLIFF](../../reference/localization/catalog-and-xliff.md)
@@ -4,3 +4,4 @@ Reference 保存可被工具、第三方包和应用严格依赖的格式、协
 和兼容性，不承担源码实现说明或使用 walkthrough。

 - [主题 Reference](theming/index.md)
+- [本地化 Reference](localization/index.md)
@@ -0,0 +1,5 @@
+# 本地化 Reference
+
+- [公共 API](public-api.md)：LanguageTag、LanguageDefinition、Manager、Localizer 和 XAML 入口。
+- [Language Catalog 与 XLIFF](catalog-and-xliff.md)：Catalog identity、XLIFF 2.1、格式化消息和覆盖规则。
+- [本地化系统架构](../../architecture/systems/localization/index.md)
@@ -2,7 +2,7 @@

 本文定义应用、类库、ViewModel、服务和 XAML 使用 AtomUI 本地化基础设施时可依赖的公共契约。
 Catalog 和 XLIFF 的源文件规则见 [catalog-and-xliff.md](catalog-and-xliff.md)，运行时语义见
-[runtime-architecture.md](runtime-architecture.md)。
+[本地化运行时架构](../../architecture/systems/localization/runtime.md)。

 ## 根 Builder