mirror of
https://github.com/vicliu624/trail-mate.git
synced 2026-08-15 15:19:45 +00:00
103 lines
3.7 KiB
Markdown
103 lines
3.7 KiB
Markdown
# UI 本地化计划
|
||
|
||
历史说明：
|
||
本文件记录的是一份较早期的实现计划，已经不再是当前的规范性设计来源。
|
||
当前本地化契约见 [`docs/LOCALIZATION_SPEC.md`](./LOCALIZATION_SPEC.md)，
|
||
pack/runtime 机制说明见 [`docs/LOCALE_PACKS.md`](./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 支持的板卡仍能安全回退到现有字体配置
|
||
|
||
## 实施步骤
|
||
|
||
1. 增加共享本地化模块与持久化辅助函数。
|
||
2. 增加菜单/应用刷新支持，使语言切换后立即生效。
|
||
3. 在 `Settings > System` 中加入 `Display Language`。
|
||
4. 将共享设置项标签、选项、提示和校验消息接入本地化。
|
||
5. 本地化菜单标题、仪表盘标签、共享组件、模态按钮和通知。
|
||
6. 本地化 Contacts / Chat / GPS / Tracker / PC Link / USB / SSTV / GNSS / Walkie Talkie / placeholder 页面中的固定文本。
|
||
7. 本地化屏保文本、电池通知、事件通知等 ESP 特定提示。
|
||
8. 运行格式化与 CI 等价构建，并修复回归问题。
|
||
|
||
## 验收标准
|
||
|
||
- 全新启动时英文是默认 UI 语言。
|
||
- 语言可以在 `Settings > System > Display Language` 中切换。
|
||
- 切换语言后当前页面立即更新。
|
||
- 返回主菜单后可看到已本地化的应用名称。
|
||
- `Back`、`Save`、`Cancel`、`Loading...`、系统 toast、页面标题等共享提示已完成本地化。
|
||
- 在支持目标上，中文文本能以 CJK glyph 覆盖正常显示。
|
||
- 现有 PlatformIO CI 构建仍能通过。
|