xous-core/locales

Localization

The lib.rs file in this crate is auto-generated by xtask. It must be manually generated by calling xtask generate-locales every time changes are made to the localization strings.

Where are the Strings?

Locale files can be added to any server by making a locales directory within the server, and then placing a .json file in there with a format like this:

{
    "mainmenu.sleep": {
        "en": "Sleep now",
        "zh": "睡眠模式",
        "en-tts": "Sleep now"
    },
    "mainmenu.backlighton": {
        "en": "Backlight on",
        "zh": "背光开启",
        "en-tts": "🔇"
    },
    "mainmenu.backlightoff": {
        "en": "Backlight off",
        "zh": "背光关闭",
        "en-tts": "🔇"
    },
    "mainmenu.closemenu": {
        "en": "Close menu",
        "zh": "关闭功能表",
        "en-tts": "Close menu"
    }
}

Note that "en-tts" is a locale for english/vision-impaired. 🔇 means that an item does not exist for that locale (can be used in any locale, not just speech-to-text locales). Omitting a locale entirely without using the 🔇 character will lead to a panic.

How to Code with Locales

The JSON file is parsed by xtask into a lib.rs file which is referred to within a server by the following idiom:

// insert `locales = {path = "../../locales"}` inside the Cargo.toml of the server
use locales::t;

name: String::<64>::from_str(t!("mainmenu.backlighton", xous::LANG)),

The t!(string_reference, language) takes string_reference which is a programmer-readable string that refers to the localized string, and language is the language code used inside the localization file.

How to Change the Display Language

A global LANG variable is provide inside xous-rs/src/locale.rs so that the language may be set by changing a single file.

Strings are statically mapped into the kernel for a given locale, so changing languages requires recompiling the OS with the appropriate code selected. This method has a few prominent pros and cons, as such:

Cons:

• Requires a recompilation and update to change the language

Pros:

• Smallest binary size
• Least memory & code execution overhead
• Simple

The recompilation issue can be handled with some CI tooling to output versions of the OS for each language with each automatic compilation pass. The updating issue is more annoying. However, any dynamic solution requires quite a bit of tooling; and given that the kernel is no_std, it's not possible to pull in full-fledged localization systems like fluent. Furthermore, we don't have a filesystem yet to store alternate language files, and the OS needs to have some prompts for the user in order to unlock the filesystem in the first place.

Nothing prevents a more sophisticated application-level server later on that operates in std from pulling in a more featureful, dynamic localization framework; but it's an explicit goal to keep the kernel small, simple, and fast.