core.i18n ========= .. py:module:: core.i18n .. autoapi-nested-parse:: Provides tools and methods for internationalization (i18n). Applications wishing to use i18n need to define two settings: :i18n.localedirs: A list of gettext locale directories. The first directory is considered to be the main directory, all other directories are added to the translation object as fallbacks. :i18n.default_locale: The fallback locale that is used if no locale more suitable to the user could be found. For example:: from onegov.core.framework import Framework from onegov.core import utils class App(Framework): pass @TownApp.setting(section='i18n', name='localedirs') def get_i18n_localedirs(): return [ utils.module_path('onegov.town6', 'locale') utils.module_path('onegov.form', 'locale') ] @TownApp.setting(section='i18n', name='default_locale') def get_i18n_default_locale(): return 'en' Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/core/i18n/translation_string/index Attributes ---------- .. autoapisummary:: core.i18n.LocaleNegotiator core.i18n._F core.i18n._M core.i18n.VALID_LANGUAGE_EXPRESSION core.i18n.POFILE_PATH_EXPRESSION Classes ------- .. autoapisummary:: core.i18n.SiteLocale Functions --------- .. autoapisummary:: core.i18n.get_i18n_localedirs core.i18n.get_i18n_locales core.i18n.get_i18n_default_locale core.i18n.get_i18n_locale_negotiatior core.i18n.default_locale_negotiator core.i18n.pofiles core.i18n.compile_translation core.i18n.get_translations core.i18n.wrap_translations_for_chameleon core.i18n.translation_chain core.i18n.get_translation_bound_meta core.i18n.get_translation_bound_form core.i18n.merge core.i18n.clone Package Contents ---------------- .. py:type:: LocaleNegotiator :canonical: Callable[[Collection[str], CoreRequest], str | None] .. py:data:: _F .. py:data:: _M .. py:data:: VALID_LANGUAGE_EXPRESSION .. py:data:: POFILE_PATH_EXPRESSION .. py:function:: get_i18n_localedirs() -> tuple[str, Ellipsis] Returns the gettext locale dir. .. py:function:: get_i18n_locales() -> None Returns the the locales actually used. .. py:function:: get_i18n_default_locale() -> None Returns the fallback language to use if the user gives no indication towards his preference (throught the request or anything). .. py:function:: get_i18n_locale_negotiatior() -> LocaleNegotiator Returns the language negotiator, which is a function that takes the current request as well as a list of available languages and returns the angauge that should be used based on that information. .. py:function:: default_locale_negotiator(locales: collections.abc.Collection[str], request: onegov.core.request.CoreRequest) -> str | None The default locale negotiator. Will select one of the given locales by: 1. Examining the 'locale' cookie which will be preferred if the language in the cookie actually exists 2. Selecting the best match from the accept_language header If no match can be found, None is returned. It is the job of caller to deal with that (possibly getting :meth:`get_i18n_default_locale`). .. py:function:: pofiles(localedir: _typeshed.StrPath) -> collections.abc.Iterator[tuple[str, str]] Takes the given directory and yields the language and the path of all pofiles found under ``*/LC_MESSAGES/*.po``. .. py:function:: compile_translation(pofile_path: str) -> gettext.GNUTranslations .. py:function:: get_translations(localedirs: collections.abc.Iterable[_typeshed.StrPath]) -> dict[str, gettext.GNUTranslations] Takes the given gettext locale directories and loads the po files found. The first found po file is assumed to be the main translations file (and should for performance reasons contain most of the translations). The other po files are added as fallbacks. The pofiles are compiled on-the-fly, using polib. This makes mofiles unnecessary. Returns a dictionary with the keys being languages and the values being GNUTranslations instances. .. py:function:: wrap_translations_for_chameleon(translations: dict[str, gettext.GNUTranslations]) -> dict[str, translationstring._ChameleonTranslate] Takes the given translations and wraps them for use with Chameleon. .. py:function:: translation_chain(translation: gettext.GNUTranslations) -> collections.abc.Iterator[gettext.GNUTranslations] Yields the translation chain with a generator. .. py:function:: get_translation_bound_meta(meta_class: type[_M], translations: gettext.GNUTranslations | None) -> type[_M] Takes a wtforms Meta class and combines our translate class with the one provided by WTForms itself. .. py:function:: get_translation_bound_form(form_class: type[_F], translate: gettext.GNUTranslations | None) -> type[_F] Returns a form setup with the given translate function. .. py:function:: merge(translations: collections.abc.Sequence[gettext.GNUTranslations]) -> gettext.GNUTranslations Takes the given translations (a list) and merges them into each other. The translations at the end of the list are overwritten by the translations at the start of the list. This is preferrable to adding fallbacks, as they increases the average complexity of the lookup function each time. Note that the translations are *not* copied before merging, so that means all existing translations are changed during this processed. To avoid this, clone the translation first (see :func:`clone`). :returns: The last GNUTranslations object with all other translation objects merged into it. The first element overrides the second and so on. .. py:function:: clone(translation: gettext.GNUTranslations) -> gettext.GNUTranslations Clones the given translation, creating an independent copy. .. py:class:: SiteLocale(locale: str) A model representing the locale of the site. Use this model to enable the user to change his locale through a path. .. py:method:: for_path(app: onegov.core.framework.Framework, locale: str) -> Self | None :classmethod: .. py:attribute:: locale .. py:method:: link(request: onegov.core.request.CoreRequest, to: str) -> str .. py:method:: redirect(request: onegov.core.request.CoreRequest) -> webob.Response