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'

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.

Module Contents

core.i18n.LocaleNegotiator: typing_extensions.TypeAlias[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: core.request.CoreRequest) str | None[source]

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 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) 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) 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 | str) Self | None[source]
redirect(request: core.request.CoreRequest) webob.Response[source]