企业官网建设流程全解析

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

GalaxyBudsClient 作为一款面向 Windows、macOS、Linux 与 Android 的非官方 Galaxy Buds 管理器，其界面本地化依赖一套以英文为基准、按语言文件分发的 ResourceDictionary 体系。本文以仓库中的乌克兰语翻译缺失报告 meta/ua.md 为入口，逐层拆解这份自动生成报告的结构与含义，并结合 LocalizationKeySourceGenerator.cs、LocalizationUtils.cs 等源码，讲清翻译键的生成、运行时解析与缺失回退机制。读完本文，你将掌握：如何读懂翻译缺失报告、缺失键在实际运行时会产生什么行为、以及如何按报告补全一份语言文件。

一、报告概览：ua.md 是什么

meta/ua.md 与同目录下的 meta/translations.md 一样，均由项目作者维护的 XamlTranslationValidator 工具自动生成并定期更新，文件头明确标注"This file is auto-generated and automatically updated. Do not modify this file manually"——该文件是只读产物，贡献者不应手工编辑它，真正的翻译工作发生在i18n/目录下的 AXAML 语言文件中。

报告核心信息有三部分：

• 翻译进度：乌克兰语（ua）当前为50%，对应294 个缺失字符串；
• 缺失清单：以表格逐行列出缺失的翻译键（Key）与其英文原文（Original string）；
• 生成来源：文件尾注"Powered by ThePBone/XamlTranslationValidator"，点明数据由外部校验工具扫描生成。

在 meta/translations.md 的总览表中可以看到所有语言的最新状态：乌克兰语与法语（fr）、罗马尼亚语（ro）同为 50%（294 个缺失键），而葡萄牙语（pt）与巴西葡萄牙语（br）已达到 98%（仅剩 7 个缺失键）。这份总览同时提供了各语言的详情页入口（如ua.md），是判断项目本地化健康度的第一手数据。

二、缺失键清单：294 个待翻译字符串全分组

以下是 meta/ua.md 报告的完整缺失键清单，按功能模块归组。这些键名同时也是 GalaxyBudsClient/i18n/en.axaml 中的x:Key标识，补全翻译时可直接对照英文原文工作。

2.1 通用与全局（23 键）

both（Both）、next（Next）、prev（Previous）、off（Off）、on（On）、hint（Hint）、help（Help）、important（Important）、home（Home）、read_failed（Failed to read file. Access denied.）、please_wait（Please wait...）、value_left_right_inline（Left: {0}, Right: {1}）、value_left_right_multiline（Left: {0} / Right: {1}）、other_x（Other ({0})）、no_data_stored（No data stored）、not_available（Not available）、last_updated_at_n（Last updated at {0}）、file_not_found（File not found）、feature_unsupported_platform（This feature is currently not supported on this platform.）、adaptive（Adaptive）、darkmode_blur_enabled（On, with blur effect）、darkmode_mica_enabled（On, with mica effect）、placement_charging（Charging）、touchoption_custom_trigger_event（Trigger earbud action...）、hotkey_add_short（New）、hotkey_edit_long（Edit existing hotkey）、event_nc_switch_one（Switch noise controls with one earbud）。

注意value_left_right_inline与value_left_right_multiline这类键包含{0}、{1}占位符，翻译时占位符位置必须原样保留，且行内/多行两种形态各自对应不同的 UI 上下文（多行版本英文原文即含换行）。

2.2 欢迎页与首次引导（8 键）

welcome_register（Set-up your earbuds）、welcome_register_desc（Choose and register your pair of Galaxy Buds）、welcome_android_hint_title（Important information for Android users）、welcome_android_hint（包含长段说明：桌面端专属功能在 Android 版不可用、与官方 Samsung Wearable 应用共存会产生连接冲突）、mainpage_header（Home）、mainpage_fit_test（Earbud fit test）、devsel_manual_pair_title（Is your device not listed?）、devsel_manual_pair_description、devsel_manual_pair（Manual connection）。

welcome_android_hint原文是跨两行的长文本，翻译时需要保留换行结构与全部技术要点（后台功能限制、官方应用冲突警告）。

2.3 设备管理页（12 键）

devices_header（Paired devices）、devices_new（New）、devices_new_long（Pair new device）、devices_select_inactive（Select）、devices_select_active（Selected）、devices_delete（Delete）、devices_delete_long（Delete device）、devices_delete_confirmation（Are you sure you want to remove this device?）、devices_settings_link（Manage paired devices）、devices_settings_link_desc（Add, remove, or select a primary device）。

2.4 触控板手势与触控锁定（19 键）

touchpad_gesture_header（Enable touchpad gestures）、touchpad_gesture_single（Single tap）、touchpad_gesture_single_desc（Play or pause track）、touchpad_gesture_double（Double tap）、touchpad_gesture_double_desc（Play next track）、touchpad_gesture_triple（Triple tap）、touchpad_gesture_triple_desc（Play previous track）、touchpad_gesture_hold（Touch and hold）、touchpad_gesture_hold_desc（Execute custom action）、touchpad_gesture_double_for_call、touchpad_gesture_double_for_call_desc（Answer call or end call）、touchpad_gesture_hold_for_call、touchpad_gesture_hold_for_call_desc（Decline call）、touchpad_default_action（Built-in touch action）、touchpad_gestures（Advanced touch lock）、touchpad_gestures_description（Disable default touch gestures）、touchpad_noise_control_mode_l、touchpad_noise_control_mode_r、touchpad_noise_control_mode_desc（Choose modes to cycle through）。

2.5 自定义触控动作（3 键）

cact_function_param（Function）、cact_hotkey_param（Hotkey）、cact_path_param（File path）。

2.6 系统信息与隐藏模式（21 键）

system_hidden_at_mode（Hidden system settings）、system_hidden_at_mode_desc（Edit hidden settings such as serial numbers and UART state）、system_usage_reports（Usage & metering reports）、system_usage_reports_desc、system_battery_statistics（Battery statistics）、system_battery_statistics_desc、system_no_response（No response from earbuds）、system_cradle_swver（Case software version）、system_cradle_serial（Case serial number）、system_btaddr_template（Local address: {0}, Peer address: {1}）、system_sku（Device SKUs）、hidden_mode_warning（Proceed with caution）、hidden_mode_warning_desc（部分修改无法通过恢复出厂设置还原，且并非所有型号都支持）、hidden_mode_target（Target device: {0} earbud）、hidden_mode_target_l_desc、hidden_mode_target_r_desc、hidden_mode_input_wrong_length（The new value must be exactly {0} characters long.）、hidden_mode_uart_on_confirm、hidden_mode_uart_off_confirm、hidden_mode_uart（Enable UART port）、hidden_mode_uart_desc、hidden_mode_power（Power menu）、hidden_mode_power_desc、hidden_mode_serial_change、hidden_mode_serial_change_desc、hidden_mode_did_change、hidden_mode_did_change_desc、hidden_mode_sku_change、hidden_mode_sku_change_desc、hidden_mode_bt_peer_addr_change、hidden_mode_bt_peer_change_desc、hidden_mode_bt_local_addr_change、hidden_mode_bt_local_change_desc、hidden_mode_terminal（Hidden command terminal）、hidden_mode_terminal_desc、power_menu_hint、power_menu_reboot（Reboot）、power_menu_shutdown（Shutdown）、power_menu_sleep（Factory sleep mode）、at_terminal_cmd_id（Command id）、at_terminal_cmd_param、at_terminal_cmd_id_invalid（含 16 位十六进制示例 0007 / 004C）、at_terminal_output（Output）、at_terminal_send（Send）。

这批键对应 HiddenModeTerminalDialog.axaml 与系统信息页等高技术密度界面，hidden_mode_target中的{0}会被替换为 Left/Right 等值，翻译时需保证语义通顺。

2.7 使用报告、计量与电池统计（30 键）

usage_reports_header、usage_reports_hint（长段说明：报告由耳机自行收集、官方 Wearable 应用会周期性重置并上报三星）、usage_reports_usage、usage_reports_metering、milliamp_hours_unit（{0}mAh）、metering_total_batt_capacity（Total battery capacity）、metering_a2dp_time（Music playback usage time (A2DP)）、metering_esco_time（Call usage time (eSCO)）、batt_hist_hint（长段说明：后台收集电量与使用数据的前提条件）、batt_hist_no_data_title、batt_hist_no_data、batt_hist_y_axis（Charge (%)）、batt_hist_last_hour、batt_hist_last_6_hours、batt_hist_last_12_hours、batt_hist_last_24_hours、batt_hist_last_3_days、batt_hist_last_7_days、batt_hist_overlay_none、batt_hist_overlay_noise_controls、batt_hist_overlay_wearing、batt_hist_overlay_host_device、batt_hist_overlay_legend（{0} (Overlay)）、batt_hist_tools_pan_and_zoom、batt_hist_tools_measure_time、batt_hist_tools_measure_battery、batt_hist_show_legend、batt_hist_measure_difference_display（Difference: {0}）、batt_hist_measure_timespan_display（Time span: {0}）、batt_hist_measure_timespan_unit_long、batt_hist_time_span_tip_title、batt_hist_control_tip_title、batt_hist_control_tip（多行鼠标操作说明）、batt_hist_overlay_tip_title、batt_hist_overlay_tip（多行叠加层说明）、batt_hist_tools_tip_title、batt_hist_tools_tip（多行工具说明）。

电池统计页对应 BatteryHistoryPage.axaml 及其后台数据收集实现 BatteryHistoryManager.cs，提示类文本（*_tip）是长多行段落，是翻译工作量最大的部分之一。

2.8 设置页（26 键）

settings_save_fail_no_access（含{0}配置文件路径占位符）、settings_appearance、settings_blurstrength、settings_blurstrength_description、settings_accent、settings_accent_description、settings_localization_description、settings_realistic_earbud_icons、settings_realistic_earbud_icons_description、settings_color_override、settings_color_override_description、settings_nav_sidebar、settings_nav_sidebar_description、settings_tray_settings、settings_dyn_tray_mode、settings_dyn_tray_mode_description、settings_dyn_tray_mode_off、settings_dyn_tray_mode_battery_min、settings_dyn_tray_mode_battery_avg、settings_devmode_description、settings_crowdsourcing、settings_cpopup_position_description、settings_crowd_header、settings_crowd_allow、settings_crowd_allow_description（众包协议说明）、settings_crowd_crashreport、settings_crowd_crashreport_description（Sentry 崩溃上报说明）。

2.9 多设备连接 Multipoint（6 键）

settings_multipoint_header、settings_multipoint_auto（Unlock multipoint without a Samsung account）、settings_multipoint_auto_description（长段原理说明：写入缺失的版本标记、放回充电盒即清除）、settings_multipoint_apply（Apply now）、settings_multipoint_apply_description、settings_multipoint_applied、settings_multipoint_failed。该功能的底层实现见 MultipointPatcher.cs。

2.10 恢复出厂设置、SmartThings Find 与佩戴测试（21 键）

factory_confirmation（多行确认文本，含"确保两只耳机均已开机"警告）、fmg_smart_things_find_manage、fmg_smart_things_find_manage_desc、fmg_smart_things_find_open、fmg_smart_things_find_open_desc、smart_things_find（SmartThings）、smart_things_find_clear、smart_things_find_clear_desc、smart_things_find_iv（Initialization vector (IV)）、smart_things_find_secret_key、smart_things_find_region、smart_things_find_fmm_token、smart_things_find_no_link、smart_things_find_write_fail、smart_things_find_write_ok、smart_things_find_write_ok_desc、gft_warning（Please wear both earbuds.）、gft_desc、gft_bad（Bad fit）、gft_good（Good fit）、gft_fail（Test failed）。

2.11 均衡器、降噪与环境音（14 键）

eq_enable_description、nc_as_anc_description、nc_one_earbud、nc_one_earbud_description、nc_ambient、nc_ambient_description、nc_voicedetect_timeout_description、nc_as_header、nc_as_custom、nc_as_custom_description、nc_as_custom_volume_l、nc_as_custom_volume_r、nc_as_custom_tone、nc_as_custom_tone_clear、nc_as_custom_tone_soft、nc_as_custom_tone_neutral、nc_as_custom_vol_normal、as_header_description、as_voicefocus_description。

2.12 高级设置与 Bixby 重映射（7 键）

adv_pause_playback、adv_pause_playback_desc（Desktop 专属说明）、adv_callpath、adv_callpath_desc、adv_extra_clear_call、adv_extra_clear_call_desc、bixby_remap_lang_desc、bixby_remap_action_desc。

2.13 连接丢失、官方应用冲突与配对（10 键）

credits_kofi、credits_github、connlost（Connection lost）、connlost_troubleshoot（Troubleshoot）、connlost_troubleshoot_title、connlost_troubleshoot_content（多行排查指南：解绑 Wearable 应用、卸载 Buds 插件、或用 Hail/Ice Box 冻结插件）、pairingmode_done、window_open（Open）、budsapp_header（Bluetooth compatibility info）、budsapp_text_p1、budsapp_text_p2、budsapp_text_p3。

2.14 固件更新（7 键）

fw_select_install_short（Install）、fw_select_from_disk_short（Open）、fw_select_refresh（Refresh）、fw_select_no_results_short（No updates found）、fw_select_verify_model_mismatch_fail（跨型号刷机可能导致永久变砖的警告，含{0}/{1}型号占位符）。

2.15 手动配对与重命名（20 键）

manualpair_title、manualpair_title_dialog、manualpair_model、manualpair_note、rename、rename_desc、rename_warn（长段说明）、rename_warn_oneui_title、rename_warn_oneui（OneUI 用户专属警告）、rename_too_short、rename_hint、rename_label、rename_reading_name、rename_ok_title、rename_ok（多行提示）。

2.16 360 空间音频（26 键）

page_spatial_audio（360 Audio）、spatial_audio_desc、spatial_enable、spatial_enable_desc、spatial_recenter、spatial_recenter_desc、spatial_demo_play、spatial_demo_stop、spatial_demo_desc、spatial_broadcast_osc、spatial_broadcast_osc_desc（localhost:9000 OSC 广播）、spatial_broadcast_opentrack、spatial_broadcast_opentrack_desc（localhost:4242 FreeTrack/OpenTrack 广播）、spatial_tracking_active、spatial_tracking_inactive、spatial_speaker_angle、spatial_speaker_angle_desc、spatial_ambience、spatial_ambience_desc、spatial_system_audio、spatial_system_audio_desc、spatial_blackhole_status_ok、spatial_blackhole_status_restart_needed、spatial_blackhole_status_missing、spatial_blackhole_missing_desc、spatial_blackhole_howto、spatial_blackhole_install、spatial_blackhole_restart、spatial_open_audio_midi、spatial_open_sound_pref、spatial_windows_info（Windows 平台 WASAPI Loopback 说明）。

360 空间音频是较新加入的功能，底层实现见 SpatialSensorManager.cs 与 SpatialAudio 平台模块，因此这批键在乌克兰语中完全缺失，属于新功能待翻译的典型示例。

三、翻译键从何处来：源生成器与语言字典

要理解"缺失"的含义，需要先明白翻译键是如何进入程序的。LocalizationKeySourceGenerator.cs 是一个 Roslyn 增量源生成器（IIncrementalGenerator），构建时扫描所有路径含i18n的.axaml文件，其工作流程如下：

1. 解析 AXAML：读取每个语言文件的<ResourceDictionary>，遍历所有<sys:String x:Key="...">节点，提取键名与英文原文（element.Value）。
2. 生成三类代码：
   • LocalizationDictionary_{langCode}.g.cs：每个语言生成一个Dictionary<string, string>，键值对直接来自 AXAML；
   • LocalizationKeys.g.cs：仅由英文文件（en.axaml）生成，把蛇形键名转换为 PascalCase 常量类，例如x:Key="hotkey_add_short"变成Keys.HotkeyAddShort，编译期就能发现键名的拼写错误；
   • LocalizationStrings.g.cs：同样仅由英文文件生成，为每个键提供Strings.XXX静态属性，内部调用Loc.Resolve(Keys.XXX)，使业务代码可以用强类型方式取字符串。
3. 生成查找表：汇总所有语言文件，生成LocalizationDictionaries.GetByLangCode(langCode)，通过 switch 表达式把"en"、"ua"等语言代码映射到对应字典。

这意味着英文文件en.axaml是键的唯一权威来源：每新增一个界面字符串，必须先在 en.axaml 中定义，源生成器才会为它生成Keys与Strings成员；其他语言文件如果缺少该键，就会在 XamlTranslationValidator 生成的报告中以"missing string"形式暴露出来——这正是ua.md中 294 条记录的产生机制。

四、缺失键的运行时行为：三级回退与动态刷新

当界面请求一个乌克兰语缺失的键时，会发生什么？答案在运行时解析器 LocalizationUtils.cs 的Loc静态类中。

4.1 三级解析链

Loc.Resolve(resName)的实际逻辑如下：

• 优先查当前语言字典（_strings，即ua字典）；
• 未命中则回退到英文基准字典（FallbackStrings，静态构造函数中通过LoadInternalLanguage("en", ...)预加载）；
• 两者都未命中时返回键名本身（如"some_key"）。

所以一个乌克兰语缺失键在界面上不会崩溃，而是直接显示英文原文——这也解释了为什么缺失报告中的"Original string"就是用户实际会看到的回退文本。ResolveOrDefault还承担了IsRightToLeft特殊键的读取，用于判断是否需要切换 RTL 布局方向（ResolveFlowDirection）。

4.2 语言加载与翻译者模式

Loc.Load()根据Settings.Data.Locale决定加载哪种语言：内部语言直接查生成字典；若语言为custom且存在custom_language.xaml（TranslatorModeFile，位于应用数据目录），则走LoadExternalLanguage从外部 XAML 文件热加载字典——这是项目内置的"翻译者模式"：翻译人员无需重新编译整个应用，把外部语言文件放到数据目录即可实时预览翻译效果。若custom模式但外部文件不存在，则自动回退英文。

4.3 语言切换实时生效

界面侧通过 TranslateExtension.cs（{Translate key}标记扩展）绑定文本。它实现了IObservable<string>，订阅时调用Loc.AddObserverForKey(key, observer)：先把当前解析结果推送给观察者，并把观察者以WeakReference形式登记到Observers字典。语言切换或字典重载后，NotifyObservers()会向所有相关键的观察者推送新值，从而让整界面无需重启即可换语言。利用弱引用可避免因未取消订阅导致的内存泄漏。

五、乌克兰语现状：已翻译内容与缺失分布

对照 ua.axaml（当前 530 行）可见，乌克兰语并非空白起步：通用按钮（okay/cancel/apply等）、连接弹窗（connpopup_*）、触控选项（touchoption_*）、托盘菜单（tray_*）、热键（hotkey_*）、事件分发（event_*）、欢迎页、主页面、更新页、设备选择、自检、设置、工厂重置、查找耳机、均衡器、降噪、环境音、高级、Bixby、致谢、连接丢失、固件更新全流程、空间传感器调试页、窗口按钮等均已翻译。

缺失部分（294 键）主要集中在报告列出的新功能与深层页面：电池统计图表的全部工具提示、360 空间音频整套文案、SmartThings Find、隐藏系统模式终端、Multipoint 解锁、以及若干新设置项与长段帮助文本。这些键在 en.axaml（当前 778 行）中均已定义，乌克兰语文件尚未跟进。

六、补全翻译的实操指南

按照仓库机制，补全乌克兰语翻译的正确流程如下（仓库为只读环境，以下描述针对本地贡献场景）：

1. 定位基准：打开 GalaxyBudsClient/i18n/en.axaml 找到缺失键的英文原文（即ua.md报告中的 Original string 列），再打开 GalaxyBudsClient/i18n/ua.axaml 在对应分组注释（如<!--Battery statistics-->）下追加<sys:String x:Key="...">译文</sys:String>。
2. 遵守格式：键名必须与英文文件完全一致；{0}、{1}占位符按乌克兰语语序重排（如Last updated at {0}可译为Востаннє оновлено: {0}）；多行文本在 AXAML 中保留换行；特殊字符（引号、反斜杠）需转义——源生成器在ParseFile中会执行\"、\\转义与换行归一化，文件格式错误会导致生成失败。
3. 验证：重新编译项目，源生成器会自动把新条目并入LocalizationDictionary_ua.g.cs；或在运行时借助翻译者模式（custom_language.xaml）免编译预览。提交后由 XamlTranslationValidator 重新扫描，ua.md与 translations.md 的进度会随之更新（注意：这两份文件由工具维护，不应手工修改）。
4. 优先级建议：从高可见度键入手（欢迎页、设备管理、连接丢失提示），再处理长文本工具提示（batt_hist_*_tip、connlost_troubleshoot_content），最后是低频调试界面（隐藏模式终端、AT 命令提示）。

七、注意事项与翻译质量要点

• 占位符一致性：hidden_mode_input_wrong_length、system_btaddr_template、fw_select_verify_model_mismatch_fail等键的{0}/{1}是运行时由代码填入的实际值（如序列号、地址、型号名），翻译时删除或改序会导致运行时文本错乱。
• 换行与分段：batt_hist_control_tip、usage_reports_hint、welcome_android_hint、rename_warn等多行键在英文中通过换行分段，乌克兰语译文应保持相同的信息层次，避免 UI 布局失衡。
• 平台差异提示：adv_pause_playback_desc标注 Desktop only、spatial_blackhole_*系列仅 macOS 相关、spatial_windows_info仅 Windows 相关，翻译时勿删减这些平台限定说明，以免误导用户。
• 术语统一：乌克兰语中 ANC（активне шумозаглушення）、Ambient sound（звукове оточення）、Case（кейс）等在 ua.axaml 已有先例，新翻译应与既有术语保持一致。

完成上述工作后，ua.md报告中的 294 条记录会逐条消失，meta/translations.md总览中乌克兰语的进度将向 100% 推进——这份自动生成的缺失报告，正是驱动 GalaxyBudsClient 多语言生态持续完善的自动化清单。

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