Providers

Locale provider interfaces and concrete implementations.

FileSystemLocaleProvider(locales_dir, backend='babel', default_locale=DEFAULT_LOCALE, strict_mode=False, backend_config=None)

Bases: LocaleProvider

Locale provider backed by a filesystem catalog structure.

Attributes:

Name	Type	Description
locales_dir	str	Path to the locales directory hierarchy.
backend_name	str	Backend identifier.
domain	str	Gettext domain for backend catalogs.

Initialize the filesystem provider.

Parameters:

Name	Type	Description	Default
locales_dir	str	Path to the locales directory hierarchy.	required
backend	str	Backend identifier. Defaults to "babel".	'babel'
default_locale	str	Default locale identifier. Defaults to DEFAULT_LOCALE.	DEFAULT_LOCALE
strict_mode	bool	Whether to enable strict error handling. Defaults to False.	False
backend_config	dict[str, Any] | None	Additional backend factory configuration, including optional "domain" key. Defaults to None.	None

Raises:

Type	Description
ProviderConfigurationError	If the backend is unsupported or directory invalid.

get_available_locales()

Return a sorted list of available locales.

Returns:

Type	Description
list[str]	list[str]: A sorted list of available locales.

has_locale(locale)

Return whether the specified locale is available.

Parameters:

Name	Type	Description	Default
locale	str	Locale identifier to check.	required

Returns:

Name	Type	Description
bool	bool	True if the locale is available, False otherwise.

LocaleNotFoundError(locale, message=None)

Bases: Exception

Raised when a requested locale is not available in the backend.

This exception is raised in strict mode when a locale is requested but cannot be found in the loaded translations.

Attributes:

Name	Type	Description
locale	str	The locale identifier that was not found.
message	str | None	Human-readable error message. Defaults to None.

Initialize LocaleNotFoundError.

Parameters:

Name	Type	Description	Default
locale	str	The locale identifier that was not found.	required
message	str | None	Optional custom error message. Defaults to None, in which case a default message is generated.	None

__str__()

Return string representation of the error.

Returns:

Name	Type	Description
str	str	Representation of the error.

LocaleProvider(default_locale=DEFAULT_LOCALE, strict_mode=False, backend='babel', backend_config=None)

Bases: ABC

Abstract base class for locale providers.

Attributes:

Name	Type	Description
default_locale	str	Fallback locale identifier.
strict_mode	bool	Strict error handling mode flag.
backend	BaseTranslationBackend	Configured translation backend instance.

Initialize the locale provider.

Parameters:

Name	Type	Description	Default
default_locale	str	Default locale identifier. Defaults to "en".	DEFAULT_LOCALE
strict_mode	bool	Whether to enable strict error handling. Defaults to False.	False
backend	str | BaseTranslationBackend	Backend identifier to instantiate. Defaults to "babel". If given as a string, it will be used to create a backend instance using create_backend. If given as a BaseTranslationBackend instance, it will be used as is.	'babel'
backend_config	dict[str, Any] | None	Configuration for backend factory. Defaults to None. Will be passed to create_backend if backend is a string.	None

Raises:

Type	Description
ValueError	If default_locale is empty or no backend can be created.
LocaleNotFoundError	If strict_mode is enabled and the default locale is absent.

get_available_locales() abstractmethod

Return a sorted list of available locales.

This method is to be implemented by subclasses to enumerate all locales they can serve (normalized as defined by the provider).

Returns:

Type	Description
list[str]	list[str]: A sorted list of available locales.

Raises:

Type	Description
NotImplementedError	If the method is not implemented by a subclass.

get_context_plural_translation(key, locale, context, count, **variables)

Return context-specific plural translation for key and context.

Parameters:

Name	Type	Description	Default
key	str	Translation key to retrieve.	required
locale	str	Locale identifier to retrieve translation for.	required
context	str	Context value to use for translation.	required
count	int	Count value to use for pluralization.	required
**variables		Additional variables to pass to the backend method.	{}

Returns:

Name	Type	Description
str	str	The context-specific plural translated text.

get_context_translation(key, locale, context, **variables)

Return context-specific translation for key and context.

Parameters:

Name	Type	Description	Default
key	str	Translation key to retrieve.	required
locale	str	Locale identifier to retrieve translation for.	required
context	str	Context value to use for translation.	required
**variables		Additional variables to pass to the backend method.	{}

Returns:

Name	Type	Description
str	str	The context-specific translated text.

get_context_translation_lazy(key, locale, context, **variables)

Return a lazy translation proxy for context-specific messages.

Parameters:

Name	Type	Description	Default
key	str	Translation key to retrieve.	required
locale	str	Locale identifier to retrieve translation for.	required
context	str	Context value to use for translation.	required
**variables		Additional variables to pass to the backend method.	{}

Returns:

Name	Type	Description
LazyProxy	LazyProxy	A lazy translation proxy for the given key and locale.

get_plural_translation(key, locale, count, **variables)

Return pluralized translation for key and count.

Parameters:

Name	Type	Description	Default
key	str	Translation key to retrieve.	required
locale	str	Locale identifier to retrieve translation for.	required
count	int	Count value to use for pluralization.	required
**variables		Additional variables to pass to the backend method.	{}

Returns:

Name	Type	Description
str	str	The pluralized translated text.

get_plural_translation_lazy(key, locale, count, **variables)

Return a lazy translation proxy for plural messages.

Parameters:

Name	Type	Description	Default
key	str	Translation key to retrieve.	required
locale	str	Locale identifier to retrieve translation for.	required
count	int	Count value to use for pluralization.	required
**variables		Additional variables to pass to the backend method.	{}

Returns:

Name	Type	Description
LazyProxy	LazyProxy	A lazy translation proxy for the given key and locale.

get_translation(key, locale, **variables)

Return translated text for key and locale.

Parameters:

Name	Type	Description	Default
key	str	Translation key to retrieve.	required
locale	str	Locale identifier to retrieve translation for.	required
**variables		Additional variables to pass to the backend method.	{}

Returns:

Name	Type	Description
str	str	The translated text.

get_translation_lazy(key, locale, **variables)

Return a lazy translation proxy for key and locale.

Parameters:

Name	Type	Description	Default
key	str	Translation key to retrieve.	required
locale	str	Locale identifier to retrieve translation for.	required
**variables		Additional variables to pass to the backend method.	{}

Returns:

Name	Type	Description
LazyProxy	LazyProxy	A lazy translation proxy for the given key and locale.

has_locale(locale) abstractmethod

Return True if the given locale is available.

This method is to be implemented by subclasses to indicate whether a locale is available.

Parameters:

Name	Type	Description	Default
locale	str	Locale identifier to check.	required

Returns:

Name	Type	Description
bool	bool	True if the locale is available, False otherwise.

Raises:

Type	Description
NotImplementedError	If the method is not implemented by a subclass.

ProviderConfigurationError(message)

Bases: Exception

Raised when provider configuration is invalid.

This exception is raised during provider initialization when the configuration parameters are invalid or inconsistent.

Common causes: 1. Both locales_dir and translations provided (mutually exclusive) 2. Neither locales_dir nor translations provided (one required) 3. Invalid file paths or malformed translation data

Attributes:

Name	Type	Description
message	str	Human-readable error message explaining the issue.

Initialize ProviderConfigurationError.

Parameters:

Name	Type	Description	Default
message	str	Error message explaining the configuration issue.	required

__str__()

Return string representation of the error.

Returns:

Name	Type	Description
str	str	Representation of the error.

TranslationKeyError(key, locale, message=None)

Bases: Exception

Raised when a translation key is not found in any locale.

This exception is raised in strict mode when a translation key is requested but cannot be found in the target locale or any fallback locales.

Attributes:

Name	Type	Description
key	str	The translation key that was not found.
locale	str	The locale where the key was requested.
message	str | None	Human-readable error message. Defaults to None, in which case a default message is generated.

Initialize TranslationKeyError.

Parameters:

Name	Type	Description	Default
key	str	The translation key that was not found.	required
locale	str	The locale where the key was requested.	required
message	str | None	Optional custom error message. Defaults to None, in which case a default message is generated.	None

__str__()

Return string representation of the error.

Returns:

Name	Type	Description
str	str	Representation of the error.