Base

Translation backend interface consumed by locale providers.

BaseTranslationBackend defines the minimum contract required by LocaleProvider implementations. Backends load format-specific resources (e.g. .mo files), return raw strings for given locales and keys, and optionally perform template interpolation. They are intentionally unaware of fallback policies or locale availability decisions, which are handled at the provider layer.

Authors

Dimitrij Ray (dimitrij.ray@gdplabs.id)

References

NONE

TranslationBackend

Bases: ABC

Abstract base class defining the translation backend interface.

All translation backends must implement this interface to ensure consistent behavior and allow the LocaleProvider to work with any backend implementation.

Backend responsibilities: 1. Load translation data from files or pre-loaded sources 2. Retrieve raw messages by key (gettext, ngettext, pgettext, npgettext) 3. Format messages with variable interpolation

Backend does NOT: 1. Implement fallback chains (LocaleProvider's responsibility) 2. Handle missing keys gracefully (returns None, provider decides) 3. Normalize locale identifiers (LocaleProvider's responsibility)

Thread Safety: 1. Implementations must be thread-safe for concurrent read operations. 2. Translation data should be loaded once and cached immutably.

format_message(message, **variables)

Format a message by interpolating variables.

This default implementation uses Python's str.format to interpolate variables. Subclasses may override this method to support alternative formatting syntaxes.

Parameters:

Name	Type	Description	Default
message	str	The message string with placeholders.	required
**variables		Mapping of placeholder names to values used for interpolation. These are forwarded as keyword arguments to str.format, e.g., {name}, {count:d}. Values need not be strings—non-strings are formatted via str.format automatically. If a required placeholder is missing or a format spec is invalid, interpolation is skipped and the original message is returned unchanged.	{}

Returns:

Name	Type	Description
str	str	The formatted message string with variables replaced.

Example

backend.format_message("Hello, {name}!", name="Alice")
backend.format_message("You have {count} messages", count=5)

get_context_message(key, locale, context) abstractmethod

Retrieve a context-aware translated message (pgettext).

Context allows disambiguating translations for the same key but with different meanings. For example, "name" could mean "person name" or "file name" depending on context.

This method must be implemented by subclasses to provide a context- specific translation for the supplied key.

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
locale	str	The locale identifier.	required
context	str	The context string to disambiguate the key.	required

Returns:

Type	Description
str | None	str | None: The translated message for the given context,
str | None	or None if the key+context combination is not found.

Example

backend.get_context_message("name", "en", "person")  # "Full Name"
backend.get_context_message("name", "en", "file")    # "Filename"

get_context_plural_message(key, locale, context, count) abstractmethod

Retrieve a context-aware plural message (npgettext).

Combines context disambiguation with plural handling. Useful when the same key needs different translations based on context AND different plural forms based on count.

This method must be implemented by subclasses to resolve a context-aware plural translation for the given key and count.

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
locale	str	The locale identifier.	required
context	str	The context string to disambiguate the key.	required
count	int	The numeric count used to determine plural form.	required

Returns:

Type	Description
str | None	str | None: The translated message with appropriate context and plural form,
str | None	or None if the key+context combination is not found.

Example

backend.get_context_plural_message("item", "en", "file", 1)  # "{count} file"
backend.get_context_plural_message("item", "en", "file", 5)  # "{count} files"

get_message(key, locale) abstractmethod

Retrieve a simple translated message (gettext).

This is the basic translation lookup - equivalent to GNU gettext's gettext() function. Returns the translated message for the given key in the specified locale.

This method must be implemented by subclasses to fetch a simple translated string from the underlying message store.

Example

backend.get_message("greeting.hello", "en")  # "Hello"
backend.get_message("greeting.hello", "fr")  # "Bonjour"
backend.get_message("nonexistent", "en")     # None

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
locale	str	The locale identifier.	required

Returns:

Type	Description
str | None	str | None: The translated message string, or None if the key is not found in the specified locale. Backend should NOT implement fallback logic - return None to let the provider handle fallback.

Raises:

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

get_plural_message(key, locale, count) abstractmethod

Retrieve a plural-aware translated message (ngettext).

This method implements CLDR plural rules to select the grammatically correct plural form based on the count. Different languages have different numbers of plural forms (English: 2, Russian: 3, Arabic: 6).

This method must be implemented by subclasses to return a pluralized translation string appropriate for the given locale and count.

Example

backend.get_plural_message("item", "en", 1)  # "{count} item"
backend.get_plural_message("item", "en", 5)  # "{count} items"
backend.get_plural_message("item", "ru", 2)  # "{count} предмета"

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
locale	str	The locale identifier.	required
count	int	The numeric count used to determine plural form.	required

Returns:

Type	Description
str | None	str | None: The translated message with the appropriate plural form, or None if the key is not found in the specified locale.

Raises:

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

load_locale(locale) abstractmethod

Load translation data for a specific locale.

This method should load and cache the translation data for the specified locale. Subsequent calls with the same locale should be idempotent (no-op if already loaded).

This method must be implemented by subclasses to load locale-specific translation resources into memory.

Parameters:

Name	Type	Description	Default
locale	str	The locale identifier (e.g., "en", "fr", "zh-Hans-CN").	required

Raises:

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

Note

Implementations should cache loaded translations for performance.