API Reference¶

Classes¶

class flufl.i18n.Application(strategy: TranslationStrategy)¶

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.

Create an Application.

Use the dedent attribute on this instance to control whether translated strings are dedented or not. This is passed straight through to the Translator instance created in the _() method.

Parameters:: strategy (TranslationStrategy) – A callable that can find catalog files for the application based on the language code.

property code: str | None¶

Return the current language code.

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

property current: Translator¶

Return the current translator.

Returns:: The current translator.

property default: str | None¶

The default language code, if there is one.

Returns:: The default language code or None.

defer() → None¶

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: str) → NullTranslations¶

Get the catalog associated with the language code.

Parameters:: language_code (str) – The language code.
Returns:: A gettext catalog.
Return type:: NullTranslations

property name: str¶

The application name.

Returns:: The application name.

pop() → None¶

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: str) → None¶

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: NullTranslations, dedent: bool = True, depth: int = 2)¶

A translation context.

Create a translation context.

Parameters:

catalog (NullTranslations) – The translation catalog.
dedent (bool) – Whether the input string should be dedented.
depth (int) – Number of stack frames to call sys._getframe() with.

property catalog: NullTranslations¶: The translation catalog.

translate(original: str, extras: Dict[str, str] | None = None) → str¶

Translate the string.

Parameters:

original (str) – The original string to translate.
extras (Dict[str, str] | None) – Extra substitution mapping, elements of which override the locals and globals.

Returns:

The translated string.

Return type:

str

class flufl.i18n.PackageStrategy(name: str, package: ModuleType)¶

A strategy that finds catalogs based on package paths.

Create a catalog lookup strategy.

Parameters:

name (str) – The application’s name.
package (ModuleType) – The package path to the message catalogs. This strategy uses the __file__ (which must exist and be a string) of the package path as the directory containing gettext messages.

class flufl.i18n.SimpleStrategy(name: str)¶

A simpler strategy for getting translations.

Create a catalog lookup strategy.

Parameters:: name (str) – The application’s name.

class flufl.i18n._registry.Registry¶

A registry of application translation lookup strategies.

register(strategy: TranslationStrategy) → Application¶

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: str) → RuntimeTranslator¶

Initialize a translation context.

Parameters:: domain (str) – The application’s name.
Returns:: The translation function, typically bound to _()
Return type:: RuntimeTranslator

flufl.i18n.expand(template: str, substitutions: ~typing.Dict[str, str], template_class: type = <class 'string.Template'>) → str¶

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.

Returns:

The substituted string.

Return type:

str

Globals¶

See the Registry class for details.

flufl.i18n.registry¶: A registry of application translation lookup strategies.

Types¶

class flufl.i18n.RuntimeTranslator¶

Abstract class representing the interface for the _() function.

abstract property code: str | None¶: The language code currently in effect, if there is one.

abstract property default: str | None¶

Return the default language code.

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

abstract defer_translation() → TranslationContextManager¶

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.

Returns:: The NULLTranslations context.
Return type:: TranslationContextManager

abstract pop() → None¶

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: str) → None¶

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: str) → TranslationContextManager¶

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.
Returns:: The new translation context.
Return type:: TranslationContextManager

class flufl.i18n.TranslationContextManager¶: Context manager for translations in a particular language.

class flufl.i18n.TranslationStrategy¶

Abstract class representing the interface for translation strategies.

abstract property name: str¶: The application’s name.