多语言模块迁移方案

本文记录从旧 ThemeManager + LanguageProvider + C# 翻译类 架构到独立应用级本地化基础设施的历史映射、兼容结果和删除边界。迁移已经完成；本文不是当前实现入口，当前契约以同目录其他文档为准。

旧实现问题

旧语言系统具有以下结构性限制：

ThemeManager 同时实现主题和 ILanguageManager，语言资源被当作主题静态资源的一部分挂载。
LanguageCode 和 LanguageVariant 只能表达 en-US、zh-CN、zh-TW。
每个语言由一份 C# 常量类表示，翻译不使用标准交换格式。
LanguageProviderAttribute、Provider 构造和资源字段曾依赖运行时 Attribute/字段反射。
LanguageProviderPool 和 IThemeManagerBuilder.AddLanguageProvider() 把本地化注册绑在主题/控件包注册上。
应用 ViewModel 和服务缺少独立、强类型、DI 中立的 ILocalizer。
第三方新增语言需要扩展固定 enum/API，无法形成静态 NuGet 翻译协议。

迁移后的对应关系

旧类型或机制	已落地替代
`LanguageCode`	`LanguageTag` + `LanguageTags`
`LanguageVariant`	`LanguageState.CurrentLanguage` / `LanguageDefinition`
`LanguageProvider` / `ILanguageProvider`	生成式 `TranslationBundleDescriptor`
`LanguageProviderAttribute`	`[LanguageCatalog]` enum + XLIFF
每语言 C# 常量类	`en-US.xlf`、`zh-CN.xlf`、`zh-TW.xlf`
`LanguageProviderPool`	`GeneratedLanguageModuleRegistration`
ThemeManager language dictionaries	`LanguageCatalogRegistry` + `LanguageSnapshot`
ThemeManager merged dictionary switching	稳定 `LanguageResourceProvider` Snapshot 交换
`WithDefaultCultureInfo()`	`UseLanguages()` + `LanguageTag.FromCultureInfo()` 边界转换
`IThemeManagerBuilder` 根入口	`IAtomUIBuilder`

必须保留的兼容面

现有应用和组件 XAML 形态必须保留：

<TextBlock Text="{atom:DatePickerLangResource Today}" />
<TextBlock Text="{atom:CommonLangResource Ok}" />

迁移后仍生成同名：

DatePickerLangResourceKind
DatePickerLangResourceExtension
CommonLangResourceKind
CommonLangResourceExtension

AtomUI 公共 Catalog 的 enum namespace、类型名和成员名应尽量保持不变，使 AXAML namespace 与资源调用无需批量改写。底层基类、descriptor、slot 和资源 Provider 可以完全替换。

明确不保留的 API

重构中已经删除：

LanguageCode
LanguageVariant
LanguageVariantTypeConverter
LanguageProvider
ILanguageProvider
LanguageProviderAttribute
LanguageProviderPool
IThemeManagerBuilder.AddLanguageProvider()
IThemeManagerBuilder.WithDefaultLanguageVariant()

不创建逐语言兼容扩展：

UseAtomUIZhCN();
UseAtomUIZhHans();
UseAtomUIJaJP();

也不保留 UseAtomUILanguages()；统一入口是根 IAtomUIBuilder 上的 UseLanguages()。

Catalog 迁移

每组现有 Provider 按 LanguageId 转成一个源代码 Catalog enum：

DatePicker en_US/zh_CN/zh_TW
  -> DatePickerLangResourceKind.cs
  -> en-US.xlf
  -> zh-CN.xlf
  -> zh-TW.xlf

迁移工具或脚本只负责一次性抽取现有常量、生成候选 XLIFF 和显式数字 ID；结果必须人工审查并进入正常源码。生成文件不能长期依赖旧 C# Provider，也不能在运行时提供双轨资源。

ID 分配规则：

以迁移时确定的 Catalog 成员清单分配从 1 开始的稳定 ID。
分配后立即写入 enum 和 XLIFF unit id，不再依赖字母排序或声明顺序。
迁移清单记录旧成员名到新 ID，防止分批迁移时不同语言产生不同编号。
已发布的 enum 底层数值如果被外部持久化，应在对应 Catalog 迁移前单独评估；不能假设现有隐式值是契约。

最终迁移结果

AtomUI.Localization、AtomUI.Build.Tasks、Localization Generator、根 IAtomUIBuilder 和静态语言包模板已经落地。
AtomUI、GalleryBase 与 Gallery Catalog 已迁移为显式数字 ID 和 XLIFF 2.1。
Desktop、DataGrid、ColorPicker、Extras 等包分别注册自身 GeneratedLanguageModuleRegistration。
Gallery 与测试应用使用 UseLanguages()、ILanguageManager 和 ILocalizer。
旧 Provider 类型、旧 Generator Walker/Writer、ThemeManager 语言状态和逐语言扩展已从源码删除。
模块主包与静态语言包的真实 NuGet 消费由 AtomUI.Localization.IntegrationTests 保护。

禁止恢复双轨

单个 Catalog 在任何可运行应用中只能由新系统提供。禁止：

同时把旧 ResourceDictionary 和新 Provider 挂到 Application。
让新 ILocalizer 回退查询旧 ThemeManager。
用 adapter 把 LanguageProvider 包装成 Translation Bundle 作为长期兼容层。
在新 Snapshot 缺值时搜索旧 Provider。

这些做法会制造两个语言状态源、重复资源通知和无法删除的过渡架构。

完成条件

迁移只有同时满足以下条件才算完成：

应用、AtomUI 控件和第三方示例都可定义并使用自己的 Catalog。
所有官方 Catalog 使用 XLIFF 2.1，三种内置语言覆盖完整。
现有 {atom:XxxLangResource Key} XAML 用法保持工作。
ThemeManager 不再拥有任何语言状态或 Provider。
仓库不存在运行时 XLIFF 解析、语言程序集扫描或旧 LanguageProvider 注册。
一个静态 I18n NuGet 可以通过 PackageReference 为新语言提供完整翻译。
普通测试、Generator/Task 测试、trim/AOT analyzer 和真实 NativeAOT publish 全部通过。

5.5 KiB Raw Blame History Unescape Escape