企业官网建设流程全解析

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

本篇指南以 GalaxyBudsClient 仓库中匈牙利语本地化状态文件（meta/hu.md）为切入点，完整解读该项目 27 语言本地化体系下的翻译进度报告结构、缺失字符串清单所映射的界面功能面，并深入源码剖析i18n/hu.axaml字典、Loc解析管线与源码生成器（LocalizationKeySourceGenerator）的工作机制。读者读完将能准确识别翻译缺口、理解键值字典的组织规范，并掌握参与该项目社区翻译的完整实操路径。

一、hu.md 是什么：一份自动生成的本地化进度报告

meta/hu.md并非手写文档，其文件头明确标注 "This file is auto-generated and automatically updated. Do not modify this file manually."（本文件由工具自动生成并自动更新，请勿手动修改）。它与meta/translations.md（总览 27 种语言的整体进度）一样，均由仓库使用的 XamlTranslationValidator 工具输出，报告末尾的 "Powered by [ThePBone/XamlTranslationValidator]" 即是证据。

该报告给出两项核心数据：

把这两组数字放到meta/translations.md的全局表中对比可以看到，匈牙利语与希伯来语（il）同为 56%、缺失 262 条，属于进度中等的语种；而 br（巴西葡萄牙语）、pt（葡萄牙语）已到 98%，仅缺失 7 条；ko（韩语）94%、31 条；cn（简体中文）、it、ru、sk、sv、tr、tw 等 93%、38 条。这份横向对照清晰地说明：hu 的翻译工作处于"持续推进、仍有大量字符串待补"的阶段。

报告中最重要的主体是一张 "Missing strings" 表，逐条列出尚未翻译的Key → 原始英文文本对，这正是贡献者补充翻译时需要逐条处理的"待办清单"。

二、262 个缺失字符串背后的功能面

缺失清单的 Key 前缀直接揭示了尚未完成匈牙利语翻译的界面模块。结合仓库源码，可以将其归纳为以下几大功能域：

通用与全局文案：both、next、prev、off、on、hint、help、important、home、please_wait、read_failed等基础字符串缺失，意味着窗口级通用文案仍在使用英文回退。

欢迎页与设备管理：welcome_register（设置你的耳塞）、welcome_android_hint（针对 Android 用户的官方应用冲突提示）、devsel_manual_pair*（手动配对引导）、devices_header、devices_new_long（配对新设备）、devices_delete_confirmation等。Android 提示文案尤其关键——它说明该应用最初面向桌面设计，后台驻留类特性（自定义触控动作、电池统计）在 Android 版本不可用，且与三星官方 Wearable 应用并存会引发连接问题。

触控板与噪音控制：touchpad_gesture_double_for_call（通话中双击接听/挂断）、touchpad_gesture_hold_for_call（通话中长按拒接）、touchpad_noise_control_mode_l/r（左右耳噪音控制切换模式）、nc_one_earbud（单耳噪音控制开关）等。

隐藏系统设置（Hidden System Settings）：system_hidden_at_mode*（编辑序列号、UART 状态等隐藏设置）、hidden_mode_*系列（UART 端口启用、电源菜单、修改序列号/DID/SN、修改蓝牙地址、AT 命令终端）、at_terminal_cmd_id（要求输入 16 位十六进制命令 ID，如 0007 或 004C）、power_menu_*（重启/关机/工厂睡眠）。这一组字符串对应 HiddenModeTerminalDialog.axaml 等开发者级界面，是工程师调测耳塞固件时最常打交道的部分。

电池统计（Battery Statistics）：batt_hist_*系列占据清单很大篇幅，涵盖时间跨度选择（最近 1/6/12/24 小时、3/7 天）、叠加层（噪音控制/佩戴状态/主机设备）、测量工具（时间差、电量差）、鼠标控制提示（拖拽平移、滚轮缩放、悬停坐标轴定向缩放）等。该功能对应 BatteryHistoryPage.axaml 与 BatteryHistoryManager.cs。

设置页（Settings）：settings_*系列覆盖外观（settings_blurstrength窗口模糊强度、settings_accent强调色）、托盘图标与启动（settings_dyn_tray_mode*）、多点连接（settings_multipoint_*，无需三星账号解锁 multipoint）、开发者模式等。注意settings_save_fail_no_access这条文案专门用于提示配置文件写入权限被操作系统拒绝的场景。

360 空间音频（Spatial Audio）：spatial_*系列是本仓库较新的功能面，包括头部追踪开关、重新定位正向、360 音频演示、OSC 广播（发送 yaw/pitch/roll 与四元数到 localhost:9000，供 DAW/插件使用）、OpenTrack 广播（FreeTrack/OpenTrack UDP 包到 localhost:4242，供飞行/驾驶模拟游戏使用）、macOS 下 BlackHole 2ch 虚拟声卡驱动的安装指引等。对应实现位于 Platform/SpatialAudio 目录。

固件更新与其他：fw_select_*（安装/打开/刷新/未找到更新）、fw_select_verify_model_mismatch_fail（固件与设备型号不匹配警告，防止刷错固件变砖）、rename_*（重命名耳塞，含 OneUI 用户注意事项）、smart_things_find_*（SmartThings Find 数据管理）、connlost_troubleshoot*（连接丢失排查指引：关闭三星官方 Wearable 应用等）等。

三、翻译字典的载体：i18n/hu.axaml

项目的语言包并非以 hu.md 存放翻译文本，而是以 Avalonia 资源字典文件形式组织在 GalaxyBudsClient/i18n 目录下，每个语言一个.axaml文件。匈牙利语文件为 i18n/hu.axaml（568 行、426 个键），英语基准文件为 i18n/en.axaml（778 行、599 个键）——两者之差正是 hu.md 报告的 262 个缺失字符串。

字典的物理结构是一个ResourceDictionary，内部以sys:String x:Key="..."形式组织，例如：

<!-- General --> <sys:String x:Key="okay">Oké</sys:String> <sys:String x:Key="left">Bal</sys:String> <sys:String x:Key="right">Jobb</sys:String> <sys:String x:Key="case">Tok</sys:String>

头部有一个特殊键language_name_en，用于存储该语言以英文表示的自称（Hungarian），供语言选择界面显示。文件内部按功能分区块并以 XML 注释标注，如<!--Touch options-->、<!--Firmware transfer errors-->、<!--Spatial test-->，与 hu.md 缺失清单的 Key 前缀一一对应。翻译字符串中大量使用{0}、{1}占位符（如connpopup_title为{0} {1}、value_left_right_inline为Left: {0}, Right: {1}），翻译时必须保留这些占位符的位置与数量。

四、底层实现：从 axaml 字典到运行时字符串

整个本地化链路由源码生成器 + 运行时解析器共同完成。

1. 编译期：LocalizationKeySourceGenerator 自动生成强类型字典

GalaxyBudsClient.Generators/Localization/LocalizationKeySourceGenerator.cs 是一个 Roslyn 增量生成器：它扫描所有路径含 "i18n" 的.axaml附加文本文件，为每个语言生成一个LocalizationDictionary_<langCode>.g.cs静态字典，例如hu键对应匈牙利语字典；随后通过ExecuteLookup汇总全部语言，生成LocalizationDictionaries.GetByLangCode(langCode)查找函数，以语言代码为 switch 键返回对应字典，未命中的语言返回null。

同时，它仅以英文文件（en.axaml）为基准，把每个x:Key的 snake_case 键名转换为 PascalCase，生成编译期可用的Keys常量类与Strings强类型访问类，并附带英文释义的 XML 文档注释（例如Keys.Case注释 "Resolves to: 'Case'"）。

2. 运行时：Loc 静态类的解析与回退

GalaxyBudsClient/Utils/Interface/LocalizationUtils.cs 中的Loc静态类负责运行时解析：

public static string Resolve(string resName) => ResolveOrDefault(resName) ?? $"{resName}"; public static string? ResolveOrDefault(string resName) => _strings.TryGetValue(resName, out var result) ? result : FallbackStrings.TryGetValue(resName, out var fallbackResult) ? fallbackResult : null;

解析优先级为：当前语言字典 → 英语回退字典（构造时固定加载的FallbackStrings）→ 原样返回 Key 名。这正是 hu.md 中缺失字符串在界面上表现为"显示英文（或 Key 名）"的根本原因。Loc.Load()依据Settings.Data.Locale加载对应语言；当翻译者模式下存在自定义语言文件（数据目录下的custom_language.xaml）时，会改走LoadExternalLanguage解析外部 XAML 字典。

3. 界面侧：Translate 标记扩展与动态刷新

TranslateExtension.cs 是 Avalonia 的MarkupExtension，实现了IObservable<string>，通过Loc.AddObserverForKey(key, observer)订阅指定键的翻译变更；Loc.NotifyObservers()在语言切换时向所有观察者推送新值，实现界面文案的即时更新而无需重启。界面用法如下（SettingsPage.axaml）：

<controls:SettingsComboBoxItem Name="AppLanguage" Content="{ext:Translate {x:Static i18N:Keys.SettingsLocalizationDisable}}" Description="{ext:Translate {x:Static i18N:Keys.SettingsLocalizationDescription}}" Symbol="LocalLanguage" ItemsSource="{Binding Source={ext:LocalesBindingSource}}" SelectedValue="{Binding Locale, Source={x:Static config:Settings.Data}}" />

其中Keys即生成器产出的强类型键常量类，LocalesBindingSource为语言枚举绑定源。此外，因 Avalonia 对UpdateSourceTrigger.Explicit支持有限，项目还提供了 LocalizationAwareComboBoxBehavior.cs 这类行为，在Loc.LanguageUpdated事件触发时通过重设ItemsSource强制刷新下拉项，保证语言切换后下拉列表立即显示新语言。

五、如何参与匈牙利语翻译

基于上述机制，补齐 hu 语言包的流程如下：

1. 获取待办清单：打开 meta/hu.md 的 Missing strings 表，得到 262 个待翻译 Key 及对应英文原文。
2. 编辑字典文件：在 i18n/hu.axaml 中对照 Key 追加<sys:String x:Key="...">匈牙利语译文</sys:String>条目。必须保持 Key 与占位符（{0}、{1}）不变，新字符串需放入</ResourceDictionary>结束标签之前；建议按英文文件的分区注释归类放置。
3. 验证：可参考仓库翻译说明（见 meta/translations.md 中指向的 wiki 链接）了解工具链细节。翻译完成后由 XamlTranslationValidator 重新生成 hu.md，进度与缺失数会自动更新。
4. 回退机制兜底：即使某键漏译，运行时也会回退到英文或 Key 名，不影响应用稳定性——这也解释了为什么"翻译进度"是渐进式而非必须一步到位。

值得注意的是，hu.md 明确标注"禁止手动修改"，因此任何翻译成果都应落在hu.axaml而非该报告文件上。

六、小结：从进度数字到可执行清单

meta/hu.md表面是一份 56% 的进度报告，实质上是一份机器可读、按 Key 精确索引的翻译待办清单。它既呈现了匈牙利语本地化的现状（262 条缺失），也通过 Key 前缀完整映射出 GalaxyBudsClient 的功能版图——从欢迎向导、触控板与噪音控制、隐藏系统设置、电池历史统计，到 360 空间音频、固件更新与 SmartThings Find。结合 LocalizationKeySourceGenerator.cs 的生成逻辑与 LocalizationUtils.cs 的解析回退链，读者可以完整理解"axaml 字典 → 生成器强类型键 → Loc 运行时解析 → Translate 标记扩展渲染"的本地化闭环，并立即上手补齐剩余字符串。

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