Base

Locale provider abstractions orchestrating fallback and backend access.

This module defines the shared LocaleProvider base class, responsible for normalizing locale identifiers, constructing fallback chains, and delegating message lookups to a BaseTranslationBackend. Concrete implementations such as FileSystemLocaleProvider implement discovery and availability checks while reusing the common fallback and interpolation logic implemented here.

Authors

Dimitrij Ray (dimitrij.ray@gdplabs.id)

References

NONE

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.