Internationalization
====================

One of pretix's major selling points is its multi-language capability. We make heavy use of Django's
`translation features`_ that are built upon `GNU gettext`_. However, Django does not provide a standard
way to translate *user-generated content*. In our case, we need to translate strings like product names
or event descriptions, so we need event organizers to be able to fill in all fields in multiple languages.

For this purpose, we use ``django-i18nfield`` which started out as part of pretix and then got refactored into
its own library. It has comprehensive documentation on how to work with its `strings`_, `database fields`_ and
`forms`_.


Forms
-----

For backwards-compatibility with older parts of pretix' code base and older plugins, ``pretix.base.forms`` still
contains a number of forms that are equivalent in name and usage to their counterparts in ``i18nfield.forms`` with
the difference that they take an ``event`` keyword argument and then set the ``locales`` argument based on
``event.settings.get('locales')``.

Useful utilities
----------------

The ``i18n`` module contains a few more useful utilities, starting with simple lazy-evaluation wrappers for formatted
numbers and dates, ``LazyDate`` and ``LazyNumber``. There also is a ``LazyLocaleException`` base class that provides
exceptions with gettext-localized exception messages.

Last, but definitely not least, we have the ``language`` context manager (``pretix.base.i18n.language``) that allows
you to execute a piece of code with a different locale:

.. code-block:: python

    with language('de'):
        render_mail_template()

This is very useful e.g. when sending an email to a user that has a different language than the user performing the
action that causes the mail to be sent.

.. _translation features: https://docs.djangoproject.com/en/4.2/topics/i18n/translation/
.. _GNU gettext: https://www.gnu.org/software/gettext/
.. _strings: https://django-i18nfield.readthedocs.io/en/latest/strings.html
.. _database fields: https://django-i18nfield.readthedocs.io/en/latest/quickstart.html
.. _forms: https://django-i18nfield.readthedocs.io/en/latest/forms.html