UI 本地化计划

历史说明：本文件记录的是一份较早期的实现计划，已经不再是当前的规范性设计来源。当前本地化契约见 docs/LOCALIZATION_SPEC.md， pack/runtime 机制说明见 docs/LOCALE_PACKS.md。尤其需要注意的是，本计划中仍保留了 display_language 这类历史概念，它们已经被当前的 locale-pack 架构取代。

目标

为基于 LVGL 的 Trail Mate 界面增加可在运行时切换的 UI 本地化能力，支持英文与中文。

默认语言：英文
支持语言：英文 / 中文
语言切换入口：Settings > System > Display Language
切换行为：立即生效，无需重启

范围

本任务覆盖设备固件自身产生的、面向用户的 UI 文本，包括：

主菜单应用名称
modules/ui_shared 下的共享 LVGL 页面
platform/esp/arduino_common/src/ui 下的 ESP 特定 LVGL 页面
共享通知、提示框、模态框标签
设置页的分类名、项目名、枚举标签、动作标签和校验消息
菜单仪表盘组件
屏保提示与设备侧状态通知

本任务不翻译以下内容：

收到的用户消息
联系人名、节点名、呼号、频道名等用户生成内容
Meshtastic、MeshCore、LXMF、RNode 这类协议品牌名
README / 文档 / 发布说明

设计

1. 翻译字典

在 modules/ui_shared 中使用共享本地化模块，包含：

ui::i18n::Language
持久化的当前语言状态
以 ui::i18n::tr(const char* english) 作为规范的字典查找入口

字典以现有英文源文本作为规范查找 key，并返回：

当语言为英文时，返回原始英文字符串
当语言为中文且存在翻译时，返回对应中文翻译
当没有找到翻译条目时，回退到原始英文字符串

这种方式在面对大量已有硬编码文本的 UI 代码库时，能够以较低风险完成本地化接入。

2. 持久化

将当前 UI 语言持久化到 settings namespace：

key：display_language
value：0 = English，1 = Chinese

3. 运行时刷新

切换语言时应当：

持久化新的语言值
刷新主菜单标签
以异步方式重建当前激活的应用页面

这样可以避免要求每一个控件都分别订阅语言变更事件。

4. 字体处理

当翻译后的文本包含非 ASCII 字符时，本地化标签应自动切换到 CJK 字体。

应使用共享字体辅助工具，以保证：

ASCII 标签继续使用原有 UI 字体
中文标签在可用时切换到 Noto CJK 字体
未编译 CJK glyph 支持的板卡仍能安全回退到现有字体配置

实施步骤

增加共享本地化模块与持久化辅助函数。
增加菜单/应用刷新支持，使语言切换后立即生效。
在 Settings > System 中加入 Display Language。
将共享设置项标签、选项、提示和校验消息接入本地化。
本地化菜单标题、仪表盘标签、共享组件、模态按钮和通知。
本地化 Contacts / Chat / GPS / Tracker / PC Link / USB / SSTV / GNSS / Walkie Talkie / placeholder 页面中的固定文本。
本地化屏保文本、电池通知、事件通知等 ESP 特定提示。
运行格式化与 CI 等价构建，并修复回归问题。

验收标准

全新启动时英文是默认 UI 语言。
语言可以在 Settings > System > Display Language 中切换。
切换语言后当前页面立即更新。
返回主菜单后可看到已本地化的应用名称。
Back、Save、Cancel、Loading...、系统 toast、页面标题等共享提示已完成本地化。
在支持目标上，中文文本能以 CJK glyph 覆盖正常显示。
现有 PlatformIO CI 构建仍能通过。

3.7 KiB Raw Blame History Unescape Escape