core.i18n

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

core.i18n.translation_string

Attributes

`LocaleNegotiator`
`_F`
`_M`
`VALID_LANGUAGE_EXPRESSION`
`POFILE_PATH_EXPRESSION`

Classes

SiteLocale

A model representing the locale of the site.

Functions

`get_i18n_localedirs`(→ tuple[str, Ellipsis])	Returns the gettext locale dir.
`get_i18n_locales`(→ None)	Returns the the locales actually used.
`get_i18n_default_locale`(→ None)	Returns the fallback language to use if the user gives no indication
`get_i18n_locale_negotiatior`(→ LocaleNegotiator)	Returns the language negotiator, which is a function that takes the
`default_locale_negotiator`(→ str \| None)	The default locale negotiator.
`pofiles`(→ Iterator[tuple[str, str]])	Takes the given directory and yields the language and the path of
`compile_translation`(→ gettext.GNUTranslations)
`get_translations`(→ dict[str, gettext.GNUTranslations])	Takes the given gettext locale directories and loads the po files
`wrap_translations_for_chameleon`(→ dict[str, ...)	Takes the given translations and wraps them for use with Chameleon.
`translation_chain`(→ Iterator[gettext.GNUTranslations])	Yields the translation chain with a generator.
`get_translation_bound_meta`(→ type[_M])	Takes a wtforms Meta class and combines our translate class with
`get_translation_bound_form`(→ type[_F])	Returns a form setup with the given translate function.
`merge`(→ gettext.GNUTranslations)	Takes the given translations (a list) and merges them into
`clone`(→ gettext.GNUTranslations)	Clones the given translation, creating an independent copy.

Package Contents

core.i18n.LocaleNegotiator: TypeAlias = Callable[[Collection[str], CoreRequest], str | None][source]

core.i18n._F[source]

core.i18n._M[source]

core.i18n.VALID_LANGUAGE_EXPRESSION[source]

core.i18n.POFILE_PATH_EXPRESSION[source]

core.i18n.get_i18n_localedirs() → tuple[str, Ellipsis][source]: Returns the gettext locale dir.

core.i18n.get_i18n_locales() → None[source]: Returns the the locales actually used.

core.i18n.get_i18n_default_locale() → None[source]: Returns the fallback language to use if the user gives no indication towards his preference (throught the request or anything).

core.i18n.get_i18n_locale_negotiatior() → LocaleNegotiator[source]: 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.

core.i18n.default_locale_negotiator(locales: Collection[str], request: onegov.core.request.CoreRequest) → str | None[source]

The default locale negotiator.

Will select one of the given locales by:

Examining the ‘locale’ cookie which will be preferred if the language in the cookie actually exists
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 get_i18n_default_locale()).

core.i18n.pofiles(localedir: _typeshed.StrPath) → Iterator[tuple[str, str]][source]: Takes the given directory and yields the language and the path of all pofiles found under */LC_MESSAGES/*.po.

core.i18n.compile_translation(pofile_path: str) → gettext.GNUTranslations[source]

core.i18n.get_translations(localedirs: Iterable[StrPath]) → dict[str, gettext.GNUTranslations][source]

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.

core.i18n.wrap_translations_for_chameleon(translations: dict[str, gettext.GNUTranslations]) → dict[str, translationstring._ChameleonTranslate][source]: Takes the given translations and wraps them for use with Chameleon.

core.i18n.translation_chain(translation: gettext.GNUTranslations) → Iterator[gettext.GNUTranslations][source]: Yields the translation chain with a generator.

core.i18n.get_translation_bound_meta(meta_class: type[_M], translations: gettext.GNUTranslations | None) → type[_M][source]: Takes a wtforms Meta class and combines our translate class with the one provided by WTForms itself.

core.i18n.get_translation_bound_form(form_class: type[_F], translate: gettext.GNUTranslations | None) → type[_F][source]: Returns a form setup with the given translate function.

core.i18n.merge(translations: Sequence[gettext.GNUTranslations]) → gettext.GNUTranslations[source]

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 clone()).

Returns:: The last GNUTranslations object with all other translation objects merged into it. The first element overrides the second and so on.

core.i18n.clone(translation: gettext.GNUTranslations) → gettext.GNUTranslations[source]: Clones the given translation, creating an independent copy.

class core.i18n.SiteLocale(locale: str)[source]

A model representing the locale of the site.

Use this model to enable the user to change his locale through a path.

classmethod for_path(app: onegov.core.framework.Framework, locale: str) → Self | None[source]

locale[source]

link(request: onegov.core.request.CoreRequest, to: str) → str[source]

redirect(request: onegov.core.request.CoreRequest) → webob.Response[source]