Internationalization (i18n)

Tsumiki supports internationalization (i18n), allowing the UI to display translated strings for tooltips, labels, notifications, and other user-facing text across multiple languages.

Supported Languages

Language	Code
English	en
Arabic	ar
German	de
Spanish	es
French	fr
Japanese	ja
Korean	ko
Dutch	nl
Portuguese	pt
Russian	ru
Chinese	zh
Turkish	tr

Configuration

Set the language in the [general] section of config.toml:

[general]
language = "en"

The default language is en (English). Changing the value requires a restart to take effect.

Translation File Structure

Translation files live in assets/i18n/<code>.json and use a nested JSON structure with dot-notation keys:

{
  "common": {
    "loading": "Loading...",
    "error": "Error",
    "ok": "OK"
  },
  "widget": {
    "battery": {
      "tooltip": "Battery",
      "low": "Low Battery",
      "charging": "Charging"
    },
    "bluetooth": {
      "tooltip": "Bluetooth",
      "connected": "Connected"
    }
  },
  "module": {
    "launcher": {
      "tooltip": "Open Application Launcher"
    }
  }
}

The top-level sections are:

• common – Shared strings (loading, error, OK, etc.)
• widget – Strings for individual widgets (battery, bluetooth, power, etc.)
• module – Strings for standalone modules (launcher, overview, etc.)

String Interpolation

Translation values support {variable} placeholders:

{
  "widget": {
    "brightness": {
      "tooltip": "Brightness: {percent}%"
    },
    "power": {
      "confirm_action": "Are you sure you want to {name}?"
    }
  }
}

Pass variables when calling the translation function:

from utils.i18n import _

tooltip = _("widget.brightness.tooltip", percent=75)
# Result: "Brightness: 75%"

msg = _("widget.power.confirm_action", name="shutdown")
# Result: "Are you sure you want to shutdown?"

Fallback Behavior

When a key is missing from the active language file, Tsumiki falls back to English (en). If the key is missing from English too, the raw key string itself is returned.

This means you can add translations incrementally – untranslated keys will display in English until a translation is provided.

Using i18n in Code

Import the convenience function _ from utils.i18n:

from utils.i18n import _

# Basic translation
label.set_text(_("widget.battery.tooltip"))

# With interpolation
label.set_text(_("widget.brightness.tooltip", percent=volume_level))

The _() function is a shorthand for get_i18n().translate(key, **kwargs).

Adding a New Language

1. Create a new JSON file in assets/i18n/ named with the language code (e.g. it.json for Italian).
2. Copy the structure from assets/i18n/en.json and translate the values.
3. Add the language code to the language enum in tsumiki.schema.json:

"language": {
  "type": "string",
  "default": "en",
  "enum": ["en", "es", "fr", "de", "ar", "zh", "ja", "ko", "pt", "ru", "tr", "nl", "it"]
}

4. Set language = "it" in your config.toml.
5. Restart Tsumiki.

Key Naming Convention

Translation keys follow a hierarchical dot-notation pattern:

<category>.<component>.<subcomponent>.<property>

Examples:

• common.loading – Common loading text
• widget.battery.tooltip – Battery widget tooltip
• widget.power.shutdown – Power menu shutdown label
• widget.bluetooth.connected – Bluetooth connected state
• module.launcher.tooltip – Launcher module tooltip

When adding new strings, follow this pattern and keep keys descriptive but concise.