=====
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 :class:`collections.abc.Mapping` object like this:

.. code-block::

    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.

.. code-block::

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

    # gettext
    factory = GettextBasedTranslatorFactory(domain, localedir)

    # mapping
    factory = MappingBasedTranslatorFactory(translations)

(``domain`` and ``localedir`` are passed to :func:`gettext.translation`).


Step 3: Create a Localizer
==========================

Create a :class:`~kivy_garden.i18n.localizer.Localizer` instance from the "translator factory" you created in Step 2.

.. code-block::

    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?":

.. code-block::

    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 :class:`kivy.event.EventDispatcher`,
and both ``Localizer.font_name`` and ``Localizer._`` are Kivy properties,
you can leverage Kivy's auto-binding feature:

.. code-block::

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

.. code-block:: yaml

    # 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.