From a43ea82e4b6257eb641fc2ad1bab61304f5232c1 Mon Sep 17 00:00:00 2001 From: chinboy Date: Mon, 10 Aug 2026 09:02:52 +0800 Subject: [PATCH] docs(Localization): separate system module and reference docs --- AGENTS.md | 2 +- docs/architecture/systems/index.md | 3 +- .../localization/generation-and-build.md | 19 +--------- .../systems/localization/index.md} | 23 +++++------- .../systems}/localization/language-packs.md | 0 .../systems/localization/runtime.md} | 0 .../systems/localization/verification.md} | 2 +- docs/modules/core/index.md | 2 +- docs/modules/localization/index.md | 37 +++++++++++++++++++ docs/reference/index.md | 1 + .../localization/catalog-and-xliff.md | 0 docs/reference/localization/index.md | 5 +++ .../localization/public-api.md | 2 +- .../2026-08-05-localization-migration.md} | 0 .../2026-08-07-pt-br-translation-review.md} | 0 15 files changed, 60 insertions(+), 36 deletions(-) rename docs/{modules => architecture/systems}/localization/generation-and-build.md (87%) rename docs/{modules/localization/overview.md => architecture/systems/localization/index.md} (85%) rename docs/{modules => architecture/systems}/localization/language-packs.md (100%) rename docs/{modules/localization/runtime-architecture.md => architecture/systems/localization/runtime.md} (100%) rename docs/{modules/localization/diagnostics-and-testing.md => architecture/systems/localization/verification.md} (99%) create mode 100644 docs/modules/localization/index.md rename docs/{modules => reference}/localization/catalog-and-xliff.md (100%) create mode 100644 docs/reference/localization/index.md rename docs/{modules => reference}/localization/public-api.md (99%) rename docs/{modules/localization/migration.md => superpowers/progress/2026-08-05-localization-migration.md} (100%) rename docs/{modules/localization/pt-br-translation-review.md => superpowers/progress/2026-08-07-pt-br-translation-review.md} (100%) diff --git a/AGENTS.md b/AGENTS.md index f42df2e1e..9fa83e059 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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) diff --git a/docs/architecture/systems/index.md b/docs/architecture/systems/index.md index 810a581d7..e8a1b7701 100644 --- a/docs/architecture/systems/index.md +++ b/docs/architecture/systems/index.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 基础设施、渲染和窗口系统在对应文档完成迁移后继续从本入口统一导航。 diff --git a/docs/modules/localization/generation-and-build.md b/docs/architecture/systems/localization/generation-and-build.md similarity index 87% rename from docs/modules/localization/generation-and-build.md rename to docs/architecture/systems/localization/generation-and-build.md index 76408eb49..d76000d5f 100644 --- a/docs/modules/localization/generation-and-build.md +++ b/docs/architecture/systems/localization/generation-and-build.md @@ -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/` 和生成目录： diff --git a/docs/modules/localization/overview.md b/docs/architecture/systems/localization/index.md similarity index 85% rename from docs/modules/localization/overview.md rename to docs/architecture/systems/localization/index.md index 2ba4fdfed..977bb005b 100644 --- a/docs/modules/localization/overview.md +++ b/docs/architecture/systems/localization/index.md @@ -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) | 运行时项目的源码职责、入口和依赖关系 | ## 项目边界 -目标源码和发布边界如下： +源码和发布边界如下： | 项目或包 | 职责 | 运行时依赖 | |---|---|---| diff --git a/docs/modules/localization/language-packs.md b/docs/architecture/systems/localization/language-packs.md similarity index 100% rename from docs/modules/localization/language-packs.md rename to docs/architecture/systems/localization/language-packs.md diff --git a/docs/modules/localization/runtime-architecture.md b/docs/architecture/systems/localization/runtime.md similarity index 100% rename from docs/modules/localization/runtime-architecture.md rename to docs/architecture/systems/localization/runtime.md diff --git a/docs/modules/localization/diagnostics-and-testing.md b/docs/architecture/systems/localization/verification.md similarity index 99% rename from docs/modules/localization/diagnostics-and-testing.md rename to docs/architecture/systems/localization/verification.md index 37f975662..d8cef0f05 100644 --- a/docs/modules/localization/diagnostics-and-testing.md +++ b/docs/architecture/systems/localization/verification.md @@ -1,7 +1,7 @@ # 本地化诊断与验证规范 本文定义多语言模块如何把错误放在正确阶段暴露，以及实现和发布必须具备的测试证据。诊断 ID 的具体注册仍 -遵守 [AtomUI 编译期诊断规范](../../engineering/compiler-diagnostics-guidelines.md)。 +遵守 [AtomUI 编译期诊断规范](../../../engineering/compiler-diagnostics-guidelines.md)。 ## 诊断所有权 diff --git a/docs/modules/core/index.md b/docs/modules/core/index.md index be63ea506..e0a0a7e8a 100644 --- a/docs/modules/core/index.md +++ b/docs/modules/core/index.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) diff --git a/docs/modules/localization/index.md b/docs/modules/localization/index.md new file mode 100644 index 000000000..26426e5dc --- /dev/null +++ b/docs/modules/localization/index.md @@ -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) diff --git a/docs/reference/index.md b/docs/reference/index.md index ede810de5..3315a726c 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -4,3 +4,4 @@ Reference 保存可被工具、第三方包和应用严格依赖的格式、协 和兼容性，不承担源码实现说明或使用 walkthrough。 - [主题 Reference](theming/index.md) +- [本地化 Reference](localization/index.md) diff --git a/docs/modules/localization/catalog-and-xliff.md b/docs/reference/localization/catalog-and-xliff.md similarity index 100% rename from docs/modules/localization/catalog-and-xliff.md rename to docs/reference/localization/catalog-and-xliff.md diff --git a/docs/reference/localization/index.md b/docs/reference/localization/index.md new file mode 100644 index 000000000..dc7ec4d67 --- /dev/null +++ b/docs/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) diff --git a/docs/modules/localization/public-api.md b/docs/reference/localization/public-api.md similarity index 99% rename from docs/modules/localization/public-api.md rename to docs/reference/localization/public-api.md index 24607df9e..a8d8d9a96 100644 --- a/docs/modules/localization/public-api.md +++ b/docs/reference/localization/public-api.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 diff --git a/docs/modules/localization/migration.md b/docs/superpowers/progress/2026-08-05-localization-migration.md similarity index 100% rename from docs/modules/localization/migration.md rename to docs/superpowers/progress/2026-08-05-localization-migration.md diff --git a/docs/modules/localization/pt-br-translation-review.md b/docs/superpowers/progress/2026-08-07-pt-br-translation-review.md similarity index 100% rename from docs/modules/localization/pt-br-translation-review.md rename to docs/superpowers/progress/2026-08-07-pt-br-translation-review.md