mirror of
https://github.com/vicliu624/trail-mate.git
synced 2026-09-25 13:13:37 +00:00
103 lines
4.5 KiB
Markdown
103 lines
4.5 KiB
Markdown
# UI Localization Plan
|
|
|
|
Historical Note:
|
|
This document records an earlier implementation plan and is no longer the current normative design source.
|
|
For the current localization contract, see [`docs/specification/LOCALIZATION_SPEC.md`](specification/LOCALIZATION_SPEC.md),
|
|
For the pack/runtime mechanism description, see [`docs/specification/LOCALE_PACKS.md`](specification/LOCALE_PACKS.md).
|
|
It is particularly important to note that historical concepts such as `display_language` are still retained in this plan.
|
|
They have been replaced by the current locale-pack architecture.
|
|
|
|
## Goal
|
|
|
|
Add UI localization capabilities that can be switched at runtime to the LVGL-based Trail Mate interface, supporting English and Chinese.
|
|
|
|
- Default language: English
|
|
- Supported languages: English / Chinese
|
|
- Language switching entrance: `Settings > System > Display Language`
|
|
- Switch behavior: effective immediately, no restart required
|
|
|
|
## Scope
|
|
|
|
This task covers user-facing UI text generated by the device firmware itself, including:
|
|
|
|
- Main menu application name
|
|
- Shared LVGL page under `modules/ui_shared`
|
|
- ESP-specific LVGL page under `platform/esp/arduino_common/src/ui`
|
|
- Shared notifications, prompt boxes, and modal box labels
|
|
- The category name, project name, enumeration label, action label, and verification message of the settings page
|
|
- Menu dashboard component
|
|
- Screen saver prompts and device-side status notifications
|
|
|
|
This task does not translate the following content:
|
|
|
|
- Received user messages
|
|
- User-generated content such as contact name, node name, call sign, channel name, etc.
|
|
- `Meshtastic`, `MeshCore`, `LXMF`, `RNode` and other protocol brand names
|
|
- README/Documentation/Release Notes
|
|
|
|
## Design
|
|
|
|
### 1. Translation dictionary
|
|
|
|
Use shared localization modules in `modules/ui_shared`, including:
|
|
|
|
- `ui::i18n::Language`
|
|
- Persistent current language status
|
|
- Use `ui::i18n::tr(const char* english)` as the canonical dictionary search entry
|
|
|
|
The dictionary uses the existing English source text as the canonical search key and returns:
|
|
|
|
- When the language is English, the original English string is returned
|
|
- When the language is Chinese and a translation exists, return the corresponding Chinese translation
|
|
- When no translation entry is found, fall back to the original English string
|
|
|
|
This method can complete localization access with lower risk when facing a large number of UI code libraries with hard-coded text.
|
|
|
|
### 2. Persistence
|
|
|
|
Persistence of the current UI language to the `settings` namespace:
|
|
|
|
- key:`display_language`
|
|
- value:`0 = English`,`1 = Chinese`
|
|
|
|
### 3. Runtime refresh
|
|
|
|
When switching languages, you should:
|
|
|
|
- Persistence of the new language value
|
|
- Refresh the main menu label
|
|
- Rebuild the currently active application page asynchronously
|
|
|
|
This avoids requiring each control to subscribe to the language change event separately.
|
|
|
|
### 4. Font handling
|
|
|
|
When the translated text contains non-ASCII characters, the localized label should automatically switch to CJK fonts.
|
|
|
|
Shared font accessibility tools should be used to ensure:
|
|
|
|
- ASCII labels continue to use the original UI font
|
|
-Chinese labels switch to Noto CJK fonts when available
|
|
-Boards without compiled CJK glyph support can still safely fall back to the existing font configuration
|
|
|
|
## Implementation steps
|
|
|
|
1. Added shared localization module and persistence auxiliary functions.
|
|
2. Add menu/application refresh support so that language switching takes effect immediately.
|
|
3. Add `Display Language` in `Settings > System`.
|
|
4. Integrate shared setting item labels, options, prompts and verification messages into localization.
|
|
5. Localize menu titles, dashboard labels, shared components, modal buttons and notifications.
|
|
6. Localize fixed text in Contacts / Chat / GPS / Tracker / PC Link / USB / SSTV / GNSS / Walkie Talkie / placeholder pages.
|
|
7. Localized screensaver text, battery notifications, event notifications and other ESP-specific prompts.
|
|
8. Run formatted and CI equivalent builds and fix regression issues.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- English is the default UI language on fresh start.
|
|
- The language can be switched in `Settings > System > Display Language`.
|
|
- The current page is updated immediately after switching the language.
|
|
- Return to the main menu to see the localized application name.
|
|
- `Back`, `Save`, `Cancel`, `Loading...`, system toast, page title and other sharing prompts have been localized.
|
|
- On supported targets, Chinese text can be displayed normally with CJK glyph overlay.
|
|
- Existing PlatformIO CI builds will still pass.
|