Usage

Step 1: Create translations

There are two types of translations supported by default.

One option is .mo files generated by the gettext toolset. The other option is a collections.abc.Mapping object like this:

translations = {
    "greeting": {
        "ja": "おはよう",
        "en": "morning",
    },
    "app title": {
        "ja": "初めてのKivyプログラム",
        "en": "My First Kivy App",
    },
}

Step 2: Create a TranslatorFactory

Create a “translator factory” from the translations you created in Step 1.

from kivy_garden.i18n.localizer import (
    GettextBasedTranslatorFactory,
    MappingBasedTranslatorFactory,
)

# gettext
factory = GettextBasedTranslatorFactory(domain, localedir)

# mapping
factory = MappingBasedTranslatorFactory(translations)

(domain and localedir are passed to gettext.translation()).

Step 3: Create a Localizer

Create a Localizer instance from the “translator factory” you created in Step 2.

from kivy_garden.i18n.localizer import Localizer

localizer = Localizer(factory)

Done

That’s it. You can now ask it “What’s the translation of this message?” or “Which font is suitable for your current language?”:

l = localizer
l.lang = "en"  # set the "current language" to "en"
print(l.font_name)  # => Roboto
print(l._("greeting"))  # => morning
print(l._("app title"))  # => My First Kivy App

l.lang = "ja"
print(l.font_name)  # => <a pre-installed Japanese font>
print(l._("greeting"))  # => おはよう
print(l._("app title"))  # => 初めてのKivyプログラム

In addition, since the Localizer is a kivy.event.EventDispatcher, and both Localizer.font_name and Localizer._ are Kivy properties, you can leverage Kivy’s auto-binding feature:

# This makes the localizer accessible in the kv namespace without any
# import statements.
localizer.install(name="l")

# in .kv files
Label:
    font_name: l.font_name
    text: l._("greeting")

When localizer.lang changes, localizer._ and localizer.font_name will also change, which causes the l.font_name and l._("greeting") above to be re-evaluated. Great! You now have a label that dynamically updates its text and font_name whenever localizer.lang changes.