企业官网建设流程全解析

• 桌面应用
• 智能硬件
• 蓝牙

导读：本文以仓库中的 meta/translations.md 为骨架，系统讲解 GalaxyBudsClient（非官方 Galaxy Buds 管理工具）的多语言（i18n）体系——包括语言包的组织形式、自动生成的翻译进度看板、缺失字符串清单的读取方法，以及隐藏在界面背后的 Loc 运行时、XAML 资源字典与 Roslyn 源生成器。读完本文，你将掌握如何解读翻译进度、理解语言文件的结构与键值约定，并了解在不修改仓库的前提下如何验证或排查翻译问题。

一、翻译状态文件是什么

meta/translations.md是一个自动生成、自动更新的本地化状态报告，文件开头明确声明 "This file is auto-generated and automatically updated. Do not modify this file manually."。也就是说，它由 CI/自动化工具产出，人工修改会在下一次生成时被覆盖，只应作为只读参考。

它解决的问题非常直接：GalaxyBudsClient 拥有 26 个语言包，维护者无法手动逐个核对每个包是否跟上英文源字符串的更新，因此需要一个看板集中展示：

• 每种语言的完成度百分比；
• 每种语言缺失的字符串数量；
• 指向每种语言详细缺失清单的链接（即同目录下的 ar.md、br.md、cn.md 等）。

该文件的生成由 ThePBone/XamlTranslationValidator）。

二、逐语言进度速览（截至本仓库快照）

下表完整收录了meta/translations.md中的全部语言进度数据。其中 “缺失字符串数” 指尚未翻译、仍回退到英文原文的键值对数量，完成度 = 已翻译字符串 / 英文源字符串总数：

几点值得注意的解读：

• 完成度最高的语言是 br（巴西葡萄牙语）与 pt（葡萄牙语），均为 98%，仅差 7 条字符串；
• 完成度最低的语言为 es（西班牙语，24%）、ja（日语，24%）与 in（印度，24%），缺失约 450 条；
• 多个语言恰好同缺 38 条（ar、cn、it、ru、sk、sv、tr、tw、vn），通常意味着它们同时落后于最近新增的同一批英文键；
• 一些语言代码带有明确的地区标签（如 ar 标注为 Argentina、sv 标注为 El Salvador，属于原始文档标注，可能与通常认知的国别不同），部分语言（fa、ja、ko）在原始表中未填写地区名称。

注意：上表数据为本仓库快照时刻的状态，项目持续演进，实际进度请以仓库中实时生成的 meta/translations.md 为准。

三、缺失字符串清单的解读方法

每个语言对应一个自动生成的详情文件，例如简体中文的 meta/cn.md。其结构如下：

• 第一段同样是自动生成声明；
• 顶部表格给出该语言的进度百分比与缺失数量；
• 主体是一张 "Missing strings" 表格，逐行列出缺失的键（Key）与该键对应的英文原文（Original string）。

以 cn 缺失清单为例，可以看到一批与「360 Audio / 空间音频」及「多设备连接（Multipoint）」相关的键尚未翻译，例如：

可以看出，这些未翻译键集中在较新的功能模块上——空间音频（头动追踪、OSC/OpenTrack 广播、BlackHole 虚拟声卡集成）与 Multipoint 解锁。这印证了进度看板的价值：新增功能上线后，新键会自动进入缺失清单，等待志愿者翻译。

阅读技巧：当某语言缺失条目与英文源对齐后，缺失清单会变短甚至为空；清单中的 "Original string" 列可直接作为翻译时的英文基准。若某个键在清单中反复出现于多个语言，通常说明它是全局新增的键，而非特定语言的遗漏。

四、语言文件与键值约定：从 i18n 目录到 Loc 运行时

翻译状态的底层数据源是 GalaxyBudsClient/i18n/ 目录下的 27 个.axaml文件（en、ar、br、cn、cz、de、es、fa、fr、gr、hu、il、in、it、ja、ko、nl、pl、pt、ro、ru、sk、sv、tr、tw、ua、vn）。其中en.axaml是英文源语言，其余语言文件必须与之保持键集合一致。

每个语言文件都是 Avalonia 的ResourceDictionary，内部用sys:String元素承载翻译条目，例如 GalaxyBudsClient/i18n/en.axaml 中的写法：

<!-- English name of this language --> <sys:String x:Key="language_name_en">English</sys:String> <sys:String x:Key="okay">Okay</sys:String> <sys:String x:Key="left">Left</sys:String> <sys:String x:Key="right">Right</sys:String> <sys:String x:Key="value_left_right_inline">Left: {0}, Right: {1}</sys:String>

几个关键约定：

• 键命名：使用snake_case，并按功能域组织前缀，例如connpopup_*（连接弹窗）、touchoption_*（触摸选项）、placement_*（佩戴状态）、settings_*、spatial_*（空间音频）等；
• 占位符：支持{0}、{1}之类的格式化参数（如value_left_right_inline），以及跨行字符串（如value_left_right_multiline），翻译时须保留占位符；
• 元数据键：language_name_en记录该语言的自称名称，供语言选择界面显示；
• 每个.axaml中缺失的键，正是 meta/cn.md 这类清单所统计的对象。

运行时，这些资源字典由 Utils/Interface/LocalizationUtils.cs 中的静态类Loc消费：

• 静态构造时预加载英文包作为FallbackStrings，保证任何语言缺失键时都能回退到英文而非空白；
• Loc.Load()根据Settings.Data.Locale（见 SettingsData.cs，默认Locales.en）加载对应语言字典；
• Loc.Resolve(key)优先查当前语言字典，查不到则回退英文，再查不到直接返回键名本身，避免 UI 出现空文本；
• Loc.ResolveFlowDirection()通过IsRightToLeft键动态切换 RTL/LTR 布局方向，为阿拉伯语等从右到左语言提供支持。

五、源码级支撑：源生成器与界面绑定

5.1 Roslyn 源生成器把 AXAML 编译进程序

meta/translations.md表格中每个语言条目（ar、cn、de…）都对应一个LocalizationDictionaries中的字典成员。这些字典并非手写，而是由 GalaxyBudsClient.Generators/Localization/LocalizationKeySourceGenerator.cs 在编译期自动生成：

• 增量生成器扫描所有路径含i18n的.axaml文件，用XDocument解析每个sys:String节点；
• 为每个语言生成LocalizationDictionary_<lang>.g.cs，内含Dictionary<string,string>字面量；
• 对英文源文件额外生成Keys（键常量类）与Strings（字符串便捷访问类）两个静态类，键名由snake_case自动转换为 PascalCase 成员名；
• 最后汇总所有语言生成LocalizationDictionaries.GetByLangCode(langCode)的 switch 查找函数——这正是Loc.LoadInternalLanguage中LocalizationDictionaries.GetByLangCode(langCode)的调用目标。

可以推断，meta/translations.md中统计的 "missing string(s)" 数量，正是以en.axaml的键集合为基准，比对各语言ResourceDictionary后得到的差值——校验工具（XamlTranslationValidator）与本源生成器都建立在同一套 XAML 键值格式之上，因此二者口径一致。

5.2 界面绑定：TranslateExtension 与动态语言切换

在 XAML 界面中，翻译通过 Interface/MarkupExtensions/TranslateExtension.cs 使用，例如{translate:Translate settings_multipoint_header}。它实现了IObservable<string>：

• ProvideValue将自身转换为 Avalonia 绑定；
• Subscribe调用Loc.AddObserverForKey(key, observer)，向Loc注册该键的观察者；
• 当Loc.Load()切换语言后，Loc.NotifyObservers()会向所有注册的观察者推送新字符串，界面文本随之即时刷新。

配合Loc.LanguageUpdated事件，应用可以在运行时无缝切换语言，而无需重启。这也解释了为什么翻译进度看板能够与发布节奏同步——新键一旦被加入en.axaml，所有语言包立即出现缺失条目。

六、翻译者视角：如何参与与自查

仓库在 README.md 的 Contributing 一节明确指出：参与翻译无需编程知识，可在提交 Pull Request 前先本地测试自定义翻译。整个工作流与本文介绍的机制完全自洽：

1. 以英文为基准：以 GalaxyBudsClient/i18n/en.axaml 为准，复制结构并翻译<sys:String>的内容，保留x:Key与{0}占位符；
2. 复用翻译者工具（Translator Mode）：仓库内置 TranslatorToolsView.axaml 开发者工具，并把自定义语言文件放在custom_language.xaml（Loc.TranslatorModeFile，位于应用数据目录）即可启用Locales.custom模式即时预览——Loc.Load()会优先读取外部文件并实时刷新 UI；
3. 提交前检查缺失清单：对照 meta/translations.md 与对应语言详情（如 meta/cn.md），确认缺失键均已补全；
4. 留意特殊键：language_name_en（语言自称）、IsRightToLeft（RTL 布局开关）等元数据键会直接影响语言选择列表与界面方向。

七、小结

meta/translations.md虽然只有一张表格，却是整个 GalaxyBudsClient 本地化体系的“仪表盘”：它由校验工具自动生成，与 GalaxyBudsClient/i18n/ 下的 27 个语言包一一对应，其缺失统计直指尚未跟上英文源的键。结合 LocalizationKeySourceGenerator.cs 的编译期字典生成、LocalizationUtils.cs 的运行时回退与观察者通知、以及 TranslateExtension.cs 的界面绑定，可以看到一条从 XAML 键值到编译产物、再到运行时动态切换的完整链路。对使用者而言，本文的表格与清单解读方法可直接用于追踪翻译滞后点；对翻译贡献者而言，这套机制意味着零编程门槛的参与路径与可本地验证的闭环。

• 桌面应用
• 智能硬件
• 蓝牙