Trait KeyLocalizer 

pub trait KeyLocalizer {
    // Required method
    fn translate(
        &self,
        key_id: &str,
        locale: &str,
        style: LabelStyle,
    ) -> Option<Cow<'static, str>>;
}

The crate’s single extension point — translate stable ids ("key_escape", "mod_gui_mac", …) into display strings.

Stable id contract

The id passed to translate is one of:

• NamedKey::key_id() — for non-printable keys, see crate::NamedKey for the full list ("key_escape", "key_arrow_up", "key_kp_7", …).
• "mod_<name>_<platform>" — for held-modifier labels emitted by crate::modifier_label: "mod_ctrl" / "mod_shift" / "mod_alt" / "mod_gui" / "mod_altgr", optionally suffixed with _mac / _win / _linux / _chromeos / _android.

New ids may be added in future versions; existing ids will never be renamed.

Style awareness

Translations may differ based on LabelStyle — e.g. Symbolic returns ↑ while Textual returns "Haut" (French). When your translation is the same for both styles, return it for both.

Fallback chain

A localizer answering for only a subset of ids (or only one locale) must return None for everything else. The crate’s runtime walks this chain on every public-API call:

1. Your custom localizer for (key_id, locale, style).
2. The compiled-in locale module for locale.
3. The English ("en") module.
4. The raw id as a last resort.

Implementing a custom localizer

Most callers use MultiLocalizer which already aggregates every locale shipped via Cargo features. Implement your own only to override or extend specific labels.

use std::borrow::Cow;
use sdl_keybridge::{KeyLocalizer, LabelStyle, MultiLocalizer};

/// Renames every macOS GUI label to "⌘ Cmd" for our brand UI.
/// Falls through (returns `None`) for everything else so the runtime
/// chain still serves the rest from MultiLocalizer.
struct BrandedLocalizer;

impl KeyLocalizer for BrandedLocalizer {
    fn translate(
        &self,
        key_id: &str,
        _locale: &str,
        _style: LabelStyle,
    ) -> Option<Cow<'static, str>> {
        match key_id {
            "mod_gui_mac" => Some(Cow::Borrowed("⌘ Cmd")),
            _ => None,
        }
    }
}

// Pass it where you'd normally pass MultiLocalizer.
let _ = BrandedLocalizer;
let _fallback = MultiLocalizer::new();

Implementing a single-locale localizer

To add a brand-new locale (rather than override one), follow the CONTRIBUTING.md recipe: copy src/locales/en.rs and wire it up behind a Cargo feature. That gets the locale into MultiLocalizer for free, which is almost always what users want.

You can also implement KeyLocalizer yourself for an unsupported locale — return Some(_) only when locale matches your code:

use std::borrow::Cow;
use sdl_keybridge::{KeyLocalizer, LabelStyle};

struct EsperantoLocalizer;

impl KeyLocalizer for EsperantoLocalizer {
    fn translate(&self, key_id: &str, locale: &str, style: LabelStyle)
        -> Option<Cow<'static, str>>
    {
        if locale != "eo" { return None; }
        use LabelStyle::*;
        let s = match (key_id, style) {
            ("key_escape", Textual)    => "Eskapi",
            ("key_return", Textual)    => "Enen",
            ("key_space",  Textual)    => "Spaco",
            _ => return None,
        };
        Some(Cow::Borrowed(s))
    }
}

Required Methods

fn translate( &self, key_id: &str, locale: &str, style: LabelStyle, ) -> Option<Cow<'static, str>>

Translate a stable id into a display string, or None if this localizer has no opinion on (key_id, locale, style).

Returning None lets the runtime fallback chain take over — see the trait-level docs for the chain order.

Implementors

impl KeyLocalizer for MultiLocalizer