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: module)
A strategy that finds catalogs based on package paths.
Create a catalog lookup strategy.
- Parameters:
name (str) – The application’s name.
package (module) – 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:
- 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:
- 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:
- class flufl.i18n.TranslationContextManager
Context manager for translations in a particular language.