Internationalisation

switch UI language and watch plural rules update live.

▶ Run in browser

Tags: ui i18n localisation text plural

A centred panel shows a greeting, a pluralised item count, and the active language name in four locales (English, French, Japanese, Arabic). Click the locale buttons or press 1-4 to switch and the greeting, plural phrasing and script all change, including Japanese CJK glyphs and a right-aligned Arabic line. Adjust the item count to watch each locale’s plural category (English one/other, Arabic zero/one/two/few/many/other) select the correct phrase.

What it demonstrates

• Loading translation tables and switching Translations.instance().locale live.

• tr(key, **kwargs) lookup with {name} interpolation and locale fallback.

• CLDR plural rules via translate_plural, incl. Arabic’s six plural categories.

• Multi-script text (Latin, Japanese, Arabic) via the engine’s font fallback chain.

• Anchored, resize-aware UI (centred Panel + VBox) with clickable locale buttons.

Controls: 1 / 2 / 3 / 4 - English / French / Japanese / Arabic (or click the buttons) Left / Right - Decrease / increase the item count (or the - / + buttons) ESC - Quit

Run: uv run python examples/features/ui/i18n.py Headless self-check: uv run python examples/features/ui/i18n.py –test

Source

"""Internationalisation: switch UI language and watch plural rules update live.

A centred panel shows a greeting, a pluralised item count, and the active
language name in four locales (English, French, Japanese, Arabic). Click the
locale buttons or press 1-4 to switch and the greeting, plural phrasing and
script all change, including Japanese CJK glyphs and a right-aligned Arabic
line. Adjust the item count to watch each locale's plural category (English
one/other, Arabic zero/one/two/few/many/other) select the correct phrase.

# /// simvx
# tags = ["ui", "i18n", "localisation", "text", "plural"]
# web = { root = "I18nDemo", width = 720, height = 480, responsive = true }
# ///

## What it demonstrates
- Loading translation tables and switching `Translations.instance().locale` live.
- `tr(key, **kwargs)` lookup with `{name}` interpolation and locale fallback.
- CLDR plural rules via `translate_plural`, incl. Arabic's six plural categories.
- Multi-script text (Latin, Japanese, Arabic) via the engine's font fallback chain.
- Anchored, resize-aware UI (centred Panel + VBox) with clickable locale buttons.

Controls:
  1 / 2 / 3 / 4   - English / French / Japanese / Arabic (or click the buttons)
  Left / Right    - Decrease / increase the item count (or the - / + buttons)
  ESC             - Quit

Run: uv run python examples/features/ui/i18n.py
Headless self-check: uv run python examples/features/ui/i18n.py --test
"""

from simvx.core import (
    AnchorPreset,
    Colour,
    Input,
    InputMap,
    Key,
    Label,
    Node,
    Panel,
    Vec2,
)
from simvx.core.i18n import Translations, tr
from simvx.core.ui import Button, HBoxContainer, VBoxContainer
from simvx.graphics import App

# Translation data (inline: no external file needed)
TRANSLATIONS = {
    "en": {
        "greeting": "Hello, {name}!",
        "item_one": "You have {count} item.",
        "item_other": "You have {count} items.",
        "language": "Language: English",
        "count_label": "Items: {count}",
        "instructions": "1=EN  2=FR  3=JA  4=AR   Left/Right = count   ESC = Quit",
    },
    "fr": {
        "greeting": "Bonjour, {name} !",
        "item_one": "Vous avez {count} objet.",
        "item_other": "Vous avez {count} objets.",
        "language": "Langue : Français",
        "count_label": "Objets : {count}",
        "instructions": "1=EN  2=FR  3=JA  4=AR   Gauche/Droite = nombre   ESC = Quitter",
    },
    "ja": {
        "greeting": "こんにちは、{name}さん！",
        "item_other": "アイテムが{count}個あります。",
        "language": "言語: 日本語",
        "count_label": "個数: {count}",
        "instructions": "1=EN  2=FR  3=JA  4=AR   ←/→ = 数   ESC = 終了",
    },
    "ar": {
        "greeting": "مرحبا، {name}!",
        "item_zero": "ليس لديك عناصر.",
        "item_one": "لديك عنصر واحد.",
        "item_two": "لديك عنصران.",
        "item_few": "لديك {count} عناصر.",
        "item_many": "لديك {count} عنصرا.",
        "item_other": "لديك {count} عنصر.",
        "language": "اللغة: العربية",
        "count_label": "العدد: {count}",
        "instructions": "1=EN  2=FR  3=JA  4=AR   ←/→   ESC",
    },
}

# Ordered locale list drives both the key bindings and the on-screen buttons.
LOCALES = [("en", "EN"), ("fr", "FR"), ("ja", "JA"), ("ar", "AR")]
_LOCALE_KEYS = {"en": Key.KEY_1, "fr": Key.KEY_2, "ja": Key.KEY_3, "ar": Key.KEY_4}
_RTL_LOCALES = {"ar"}

PANEL_W, PANEL_H = 560.0, 340.0


class I18nDemo(Node):
    """Root scene: a centred panel that swaps its language and plural forms live."""

    def on_ready(self):
        ts = Translations.instance()
        ts.load_dict(TRANSLATIONS)
        ts.locale = "en"
        self._item_count = 5

        # Key bindings: 1-4 select a locale, arrows change the count, ESC quits.
        for code, key in _LOCALE_KEYS.items():
            InputMap.add_action(f"locale_{code}", [key])
        InputMap.add_action("count_down", [Key.LEFT])
        InputMap.add_action("count_up", [Key.RIGHT])
        InputMap.add_action("quit", [Key.ESCAPE])

        # Centred panel: symmetric margins around the screen centre keep it put
        # at any window size, so the layout stays legible and resize-aware.
        panel = Panel(name="Panel")
        panel.set_anchor_preset(AnchorPreset.CENTER)
        panel.margin_left = -PANEL_W / 2
        panel.margin_right = PANEL_W / 2
        panel.margin_top = -PANEL_H / 2
        panel.margin_bottom = PANEL_H / 2
        panel.bg_colour = Colour.hex("#1A1A2E")
        self.add_child(panel)

        # Vertical stack filling the panel with a small inset. FULL_RECT
        # stretches both axes, so all four margins are positive insets.
        column = VBoxContainer(name="Column")
        column.separation = 14.0
        column.set_anchor_preset(AnchorPreset.FULL_RECT)
        column.margin_left = 26
        column.margin_right = 26
        column.margin_top = 22
        column.margin_bottom = 22
        panel.add_child(column)

        self._title = self._add_label(column, font_size=20.0, colour=Colour.WHITE, align="center")
        self._greeting = self._add_label(column, font_size=18.0, colour=Colour.hex("#FFD166"))
        self._plural = self._add_label(column, font_size=16.0, colour=Colour.WHITE)
        self._language = self._add_label(column, font_size=14.0, colour=Colour.LIGHT_GRAY)

        # Item-count row: minus / plus buttons flanking the live count.
        count_row = HBoxContainer(name="CountRow")
        count_row.separation = 10.0
        self._minus = minus = Button("-", on_press=lambda: self._change_count(-1))
        minus.size = Vec2(40, 30)
        count_row.add_child(minus)
        self._count_label = Label("")
        self._count_label.font_size = 14.0
        self._count_label.size = Vec2(120, 30)
        self._count_label.alignment = "center"
        count_row.add_child(self._count_label)
        self._plus = plus = Button("+", on_press=lambda: self._change_count(1))
        plus.size = Vec2(40, 30)
        count_row.add_child(plus)
        column.add_child(count_row)

        # Clickable locale buttons mirror the 1-4 keys for mouse/touch play.
        button_row = HBoxContainer(name="Locales")
        button_row.separation = 8.0
        self._locale_buttons: dict[str, Button] = {}
        for code, short in LOCALES:
            btn = Button(short, on_press=lambda c=code: self._set_locale(c))
            btn.size = Vec2(108, 34)
            self._locale_buttons[code] = btn
            button_row.add_child(btn)
        column.add_child(button_row)

        self._help = self._add_label(column, font_size=12.0, colour=Colour.GRAY, align="center")

        self._refresh()

    @staticmethod
    def _add_label(parent, *, font_size: float, colour, align: str = "left") -> Label:
        label = Label("")
        label.font_size = font_size
        label.text_colour = colour
        label.alignment = align
        parent.add_child(label)
        return label

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        for code, _short in LOCALES:
            if Input.is_action_just_pressed(f"locale_{code}"):
                self._set_locale(code)
                break
        if Input.is_action_just_pressed("count_up"):
            self._change_count(1)
        if Input.is_action_just_pressed("count_down"):
            self._change_count(-1)

    def _set_locale(self, code: str):
        Translations.instance().locale = code
        self._refresh()

    def _change_count(self, delta: int):
        self._item_count = max(0, self._item_count + delta)
        self._refresh()

    def _refresh(self):
        ts = Translations.instance()
        rtl = ts.locale in _RTL_LOCALES
        # Right-align the translated body lines for right-to-left locales so the
        # presentation reads in the correct direction.
        body_align = "right" if rtl else "left"

        self._title.text = f"SimVX i18n Demo [{ts.locale.upper()}]"
        self._greeting.text = tr("greeting", name="Player")
        self._plural.text = ts.translate_plural("item", self._item_count)
        self._language.text = tr("language")
        self._help.text = tr("instructions")
        for label in (self._greeting, self._plural, self._language):
            label.alignment = body_align

        # The count row is localised too: it goes through tr() like the other body lines.
        self._count_label.text = tr("count_label", count=self._item_count)

        # Highlight the active locale button so the current language is obvious.
        for code, btn in self._locale_buttons.items():
            btn.set_visual_state_override("pressed" if code == ts.locale else None)


def _selftest() -> bool:
    """Headless: switch locale by key and by button, and walk the plural categories.

    Both routes into a locale are driven the way a player drives them -- a key
    press through the action map, a click on the button's own rectangle -- and the
    result is read back off the labels. The plural claim is the interesting one, so
    the Arabic count is stepped through values that select each of its six
    categories and the phrases are required to be six different strings.
    """
    from simvx.core.testing import InputSimulator
    from simvx.core.ui.testing import UITestHarness

    harness = UITestHarness(I18nDemo(name="I18nDemo"), screen_size=(720, 480))
    scene = harness.tree.root
    sim = InputSimulator(tree=harness.tree)
    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    def tap(key: Key) -> None:
        """One frame with the key down: the scene reads it as just-pressed."""
        sim.press_key(key)
        harness.tick()
        sim.release_key(key)

    harness.tick()
    check("it opens in English", Translations.instance().locale == "en", scene._language.text)

    by_key = {}
    for code, _short in LOCALES:
        tap(_LOCALE_KEYS[code])
        by_key[code] = (Translations.instance().locale, scene._language.text, scene._greeting.text)
    check(
        "each number key selects its locale and relabels the whole panel",
        all(got == code for code, (got, _, _) in by_key.items())
        and len({lang for _, lang, _ in by_key.values()}) == len(LOCALES),
        " | ".join(lang for _, lang, _ in by_key.values()),
    )
    check(
        "and the greeting is translated with the name interpolated into it",
        all("Player" in greeting for _, _, greeting in by_key.values()),
        " | ".join(greeting for _, _, greeting in by_key.values()),
    )

    # The buttons are the mouse route to the same switch, and the active one is
    # held in its pressed look so the current language is visible.
    harness.click(scene._locale_buttons["fr"])
    harness.tick()
    pressed = {code: btn.visual_state_override for code, btn in scene._locale_buttons.items()}
    check(
        "clicking a locale button switches too, and only that button stays pressed",
        Translations.instance().locale == "fr"
        and [code for code, state in pressed.items() if state is not None] == ["fr"],
        f"{scene._language.text}; pressed = {[c for c, s in pressed.items() if s is not None]}",
    )

    # Right-to-left locales right-align the translated body lines.
    harness.click(scene._locale_buttons["ar"])
    harness.tick()
    rtl = {label.alignment for label in (scene._greeting, scene._plural, scene._language)}
    harness.click(scene._locale_buttons["en"])
    harness.tick()
    ltr = {label.alignment for label in (scene._greeting, scene._plural, scene._language)}
    check(
        "the Arabic body reads right to left and the English one left to right",
        rtl == {"right"} and ltr == {"left"},
        f"ar {rtl.pop()}, en {ltr.pop()}",
    )

    # English has two plural forms; the count is only ever moved by clicking the
    # row's own buttons, so their wiring is part of every count below.
    def set_count(target: int) -> None:
        button = scene._plus if target > scene._item_count else scene._minus
        for _ in range(abs(target - scene._item_count)):
            harness.click(button)
        harness.tick()

    set_count(1)
    one = scene._plural.text
    harness.click(scene._plus)
    harness.tick()
    two = scene._plural.text
    check(
        "English picks the singular at one and the plural at two",
        one.endswith("item.") and two.endswith("items.") and scene._item_count == 2,
        f"{one} / {two}",
    )

    for _ in range(4):
        harness.click(scene._minus)
    harness.tick()
    check(
        "the minus button stops at zero rather than going negative",
        scene._item_count == 0,
        f"count = {scene._item_count} after four more clicks from two",
    )

    # Arabic's six CLDR categories, each selected by a count that falls in it.
    harness.click(scene._locale_buttons["ar"])
    harness.tick()
    phrases = {}
    for count, category in ((0, "zero"), (1, "one"), (2, "two"), (3, "few"), (11, "many"), (100, "other")):
        set_count(count)
        phrases[category] = scene._plural.text
    check(
        "Arabic selects a different phrase for each of its six plural categories",
        len(set(phrases.values())) == 6
        and all(
            phrases[c] == TRANSLATIONS["ar"][f"item_{c}"].replace("{count}", str(n))
            for c, n in (("zero", 0), ("one", 1), ("two", 2), ("few", 3), ("many", 11), ("other", 100))
        ),
        ", ".join(phrases),
    )

    harness.teardown()
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="SimVX i18n Demo", width=720, height=480).run(I18nDemo())