API Reference

Classes

class flufl.i18n.Application(strategy)

Manage all the catalogs for a particular application.

You can ask the application for a specific catalog based on the language code. The Application requires a strategy for finding catalog files.

Attributes:

  • dedent (default True) - controls whether translated strings are dedented or not. This is passed through to the underlying Translator instance.

  • depth (default 2) - The number of stack frames to call sys._getframe() with in the underlying Translator instance. Passed through to that class’s constructor.

property code: Optional[str]

Return the current language code.

Return type

Optional[str]

Returns

The current language code, or None if there isn’t one.

property current: flufl.i18n._translator.Translator

Return the current translator.

Return type

Translator

Returns

The current translator.

property default: Optional[str]

The default language code, if there is one.

Return type

Optional[str]

Returns

The default language code or None.

defer()

Push a deferred (i.e. null) translation context onto the stack.

This is primarily used to support the _.defer_translation() context manager.

Return type

None

get(language_code)

Get the catalog associated with the language code.

Parameters

language_code (str) – The language code.

Return type

NullTranslations

Returns

A gettext catalog.

property name: str

The application name.

Return type

str

Returns

The application name.

pop()

Pop the current catalog off the translation stack.

No exception is raised for under-runs. In that case, pop() just no-ops and the null translation becomes the current translation context.

Return type

None

push(language_code)

Push a new catalog onto the stack.

The translation catalog associated with the language code now becomes the currently active translation context.

Parameters

language_code (str) – The language code for the translation context.

Return type

None

class flufl.i18n._translator.Translator(catalog, dedent=True, depth=2)

A translation context.

property catalog: gettext.NullTranslations

The translation catalog.

Return type

NullTranslations

translate(original, extras=None)

Translate the string.

Parameters
  • original (str) – The original string to translate.

  • extras (Optional[Dict[str, str]]) – Extra substitution mapping, elements of which override the locals and globals.

Return type

str

Returns

The translated string.

class flufl.i18n.PackageStrategy(name, package)

A strategy that finds catalogs based on package paths.

class flufl.i18n.SimpleStrategy(name)

A simpler strategy for getting translations.

class flufl.i18n._registry.Registry

A registry of application translation lookup strategies.

register(strategy)

Add an association between an application and a lookup strategy.

Parameters

strategy (TranslationStrategy) – An application translation lookup strategy.

Returns

An application instance which can be used to access the language catalogs for the application.

Return type

Application

Functions

flufl.i18n.initialize(domain)

A convenience function for setting up translation.

Parameters

domain (str) – The application’s name.

Return type

RuntimeTranslator

Returns

The translation function, typically bound to _()

flufl.i18n.expand(template, substitutions, template_class=<class 'string.Template'>)

Expand string template with substitutions.

Parameters
  • template (str) – A PEP 292 $-string template.

  • substitutions (Dict[str, str]) – The substitutions dictionary.

  • template_class (type) – The template class to use.

Return type

str

Returns

The substituted string.

Globals

See the Registry class for details.

flufl.i18n.registry

A registry of application translation lookup strategies.

Types

class flufl.i18n.RuntimeTranslator
property code: Optional[str]

The language code currently in effect, if there is one.

Return type

Optional[str]

property default: Optional[str]

Return the default language code.

Return type

Optional[str]

Returns

The default language code, or None if there is no default language.

abstract defer_translation()

Push a NullTranslations onto the stack.

This is useful for when you want to mark strings statically for extraction but you want to defer translation of the string until later.

Return type

TranslationContextManager

Returns

The NULLTranslations context.

abstract pop()

Pop the current catalog off the translation stack.

No exception is raised for under-runs. In that case, pop() just no-ops and the null translation becomes the current translation context.

Return type

None

abstract push(language_code)

Push a new catalog onto the stack.

The translation catalog associated with the language code now becomes the currently active translation context.

Parameters

language_code (str) – The language code for the translation context.

Return type

None

abstract using(language_code)

Create a context manager for temporary translation.

While in this context manager, translations use the given language code. When the with statement exits, the original language is restored. These are nestable.

Parameters

language_code (str) – The language code for the translation context.

Return type

TranslationContextManager

Returns

The new translation context.

class flufl.i18n.TranslationContextManager

Context manager for translations in a particular language.

class flufl.i18n.TranslationStrategy
property name: str

The application’s name.

Return type

str