trail-mate/docs/ui_localization_plan.md

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, For the pack/runtime mechanism description, see docs/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.