# 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.