Index

A collection of utilities for internationalization and localization.

DetectionConfig

Bases: BaseModel

Configuration options for the language detector.

Attributes:

Name	Type	Description
confidence_threshold	float	Minimum confidence required to accept detection results.
batch_size	int	Maximum number of texts processed per batch.
fallback_language	str | None	Language code to return when detection confidence is insufficient.
max_alternatives	int	Maximum number of alternative detections to return.

validate_fallback_language(value) classmethod

Validate optional fallback language code format.

Parameters:

Name	Type	Description	Default
value	str | None	Optional fallback language code to validate.	required

Returns:

Type	Description
str | None	str | None: Validated fallback language code, or None if no fallback language is specified.

Raises:

Type	Description
ValueError	If fallback language code is invalid.

DetectionResult

Bases: BaseModel

Represents a complete language detection result.

Attributes:

Name	Type	Description
language	Language	Primary detected language candidate.
alternatives	list[Language]	Alternative detection candidates sorted by confidence descending.
is_fallback	bool	Indicates whether the result comes from fallback logic.

validate_alternatives()

Validate alternative detections ordering, size, and confidence bounds.

Returns:

Name	Type	Description
DetectionResult	'DetectionResult'	Validated detection result.

Language

Bases: BaseModel

Represents a single language detection candidate.

Attributes:

Name	Type	Description
language_code	str	ISO 639-1 language code (e.g., "en").
confidence	float	Detection confidence score between 0.0 and 1.0.

LanguageDetector(config=None, engine=None)

Orchestrates detection workflow using a pluggable DetectionEngine.

Attributes:

Name	Type	Description
config	DetectionConfig	Detector configuration.

Initialize the detector with optional configuration.

Parameters:

Name	Type	Description	Default
config	DetectionConfig | None	Detector configuration to use. Defaults to None.	None
engine	DetectionEngine | None	Detection engine instance. Defaults to None.	None

config property

Return the detector configuration.

Returns:

Name	Type	Description
DetectionConfig	DetectionConfig	Current detector configuration.

batch_detect(texts, fallback_language=None, confidence_threshold=None, config=None)

Detect languages for a batch of texts preserving order.

Parameters:

Name	Type	Description	Default
texts	list[str]	Input texts to evaluate.	required
fallback_language	str | None	Fallback language code when detection confidence is low. Defaults to None.	None
confidence_threshold	float | None	Confidence threshold below which fallback is used. Defaults to None.	None
config	DetectionConfig | None	Explicit configuration overrides. Defaults to None.	None

Returns:

Type	Description
list[DetectionResult]	list[DetectionResult]: Detection outcomes corresponding to the input texts.

Raises:

Type	Description
TypeError	If texts is not provided as a list.
ValueError	If configuration overrides are invalid.

detect(text, fallback_language=None, confidence_threshold=None, config=None)

Detect language for a single text using provided overrides.

Parameters:

Name	Type	Description	Default
text	str	Input text to evaluate.	required
fallback_language	str | None	Fallback language code when detection confidence is low. Defaults to None.	None
confidence_threshold	float | None	Confidence threshold below which fallback is used. Defaults to None.	None
config	DetectionConfig | None	Explicit configuration overrides. Defaults to None.	None

Returns:

Name	Type	Description
DetectionResult	DetectionResult	Detection outcome for the provided text.

Raises:

Type	Description
ValueError	If configuration overrides are invalid.

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.

NormalizationForm

Bases: StrEnum

Unicode normalization forms (See: [1]).

Attributes:

Name	Type	Description
NFD	str	Canonical Decomposition.
NFC	str	Canonical Composition.
NFKD	str	Compatibility Decomposition.
NFKC	str	Compatibility Composition.

coerce(form) classmethod

Coerce a normalization form input into a NormalizationForm enum value.

Parameters:

Name	Type	Description	Default
form	NormalizationForm | str	Candidate normalization form to coerce.	required

Returns:

Name	Type	Description
NormalizationForm	'NormalizationForm'	Enum value representing the normalization form.

Raises:

Type	Description
ValueError	If form is not a supported normalization form.

validate(form) classmethod

Validate normalization form strings against NormalizationForm enum.

Parameters:

Name	Type	Description	Default
form	str	Normalization form candidate to validate.	required

Raises:

Type	Description
ValueError	If form is not one of the supported normalization forms.

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.

SupportedScripts

Bases: StrEnum

Enumerates ICU-supported script targets for transliteration.

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.

TranslationManager(provider, default_locale=None)

Convenience API layer for translation operations.

TranslationManager wraps a LocaleProvider and maintains a current locale context, allowing translation methods to be called without explicitly passing the locale parameter each time.

This layer is optional - applications can use LocaleProvider directly if they prefer explicit locale parameters.

Thread Safety

The current_locale attribute is instance-specific. For multi-threaded applications (e.g., web servers), either: 1. Create a manager instance per request/thread, or 2. Use LocaleProvider directly with explicit locale parameters

Attributes:

Name	Type	Description
provider	LocaleProvider	The LocaleProvider instance.
current_locale	str	Currently active locale identifier.

Initialize TranslationManager with a provider.

Parameters:

Name	Type	Description	Default
provider	LocaleProvider	LocaleProvider instance to delegate to.	required
default_locale	str | None	Initial locale to set. Defaults to None, in which case the provider's default locale is used.	None

Raises:

Type	Description
ValueError	If provider is None.
LocaleNotFoundError	If default_locale is not available (strict mode only).

Example

from gllm_intl.translation.manager import TranslationManager
from gllm_intl.translation.providers import FileSystemLocaleProvider

provider = FileSystemLocaleProvider(
    locales_dir="./locales",
    backend="babel",
    default_locale="en",
    strict_mode=False,
)
manager = TranslationManager(provider)

manager.set_locale("fr")
print(manager.translate("greeting"))  # "Bonjour"

get_locale()

Get the current locale.

Returns:

Name	Type	Description
str	str	Current locale identifier.

Example

manager.get_locale()

set_locale(locale)

Set the current locale for subsequent translation operations.

Parameters:

Name	Type	Description	Default
locale	str	Locale identifier to set as current.	required

Raises:

Type	Description
LocaleNotFoundError	If locale not available (strict mode only).
ValueError	If locale is empty.

Example

manager.set_locale("fr")
manager.set_locale("en-US")

translate(key, **variables)

Translate a message using the current locale (gettext).

Convenience method that uses current_locale automatically.

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
**variables		Variables for message interpolation.	{}

Returns:

Name	Type	Description
str	str	Translated and formatted message string.

Raises:

Type	Description
TranslationKeyError	If key not found (strict mode only).

Example

manager.set_locale("fr")
manager.translate("greeting.hello", name="Alice")

translate_context(key, context, **variables)

Translate a context-aware message using the current locale (pgettext).

Convenience method that uses current_locale automatically.

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
context	str	Context string for disambiguation.	required
**variables		Variables for message interpolation.	{}

Returns:

Name	Type	Description
str	str	Translated message for the given context.

Raises:

Type	Description
TranslationKeyError	If key+context not found (strict mode only).

Example

manager.set_locale("en")
manager.translate_context("name", context="person")

translate_context_plural(key, context, count, **variables)

Translate a context+plural message using current locale (npgettext).

Convenience method that uses current_locale automatically.

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
context	str	Context string for disambiguation.	required
count	int	Numeric count for plural form selection.	required
**variables		Variables for message interpolation.	{}

Returns:

Name	Type	Description
str	str	Translated message with context and correct plural form.

Raises:

Type	Description
TranslationKeyError	If key+context not found (strict mode only).

Example

manager.set_locale("en")
manager.translate_context_plural("item", context="file", count=5)

translate_lazy(key, **variables)

Get a lazy translation using the current locale (lazy gettext).

Returns a LazyProxy that evaluates the translation when converted to string.

Convenience method that uses current_locale automatically.

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
**variables		Variables for message interpolation.	{}

Returns:

Name	Type	Description
LazyProxy	LazyProxy	Object that evaluates translation on demand.

Example

manager.set_locale("en")
label = manager.translate_lazy("form.username")
print(str(label))  # Evaluates now

translate_plural(key, count, **variables)

Translate a plural message using the current locale (ngettext).

Convenience method that uses current_locale automatically.

Parameters:

Name	Type	Description	Default
key	str	The message key/identifier.	required
count	int	Numeric count for plural form selection.	required
**variables		Variables for message interpolation.	{}

Returns:

Name	Type	Description
str	str	Translated message with correct plural form.

Raises:

Type	Description
TranslationKeyError	If key not found (strict mode only).

Example

manager.set_locale("en")
manager.translate_plural("item", count=5)

_(key, **variables)

Translate a message using the current thread locale.

Examples:

set_locale("fr")
message = _("greeting")
print(message)
# Bonjour

Parameters:

Name	Type	Description	Default
key	str	Message identifier.	required
**variables	Any	Named interpolation values for the message template.	{}

Returns:

Name	Type	Description
str	str	Translated message string.

Raises:

Type	Description
RuntimeError	If configuration is missing or no locale has been set.
TranslationKeyError	If the key is unknown while strict mode is enabled.

batch_detect_language(texts, engine='lingua', fallback_language=None, confidence_threshold=None, config=None)

Detect languages for multiple texts preserving input order.

Parameters:

Name	Type	Description	Default
texts	list[str]	Input texts to detect languages from.	required
engine	str	Detection engine to use. Defaults to "lingua".	'lingua'
fallback_language	str | None	Fallback language code when detection confidence is low. Defaults to None.	None
confidence_threshold	float | None	Confidence threshold below which fallback is used. Defaults to None.	None
config	DetectionConfig | None	Detection configuration overriding defaults. Defaults to None.	None

Returns:

Type	Description
list[DetectionResult]	list[DetectionResult]: Detection outcomes matching the input order.

Raises:

Type	Description
ValueError	If an unsupported engine is requested or configuration overrides are invalid.

configure_i18n(provider, force=False)

Configure the global translation manager.

Parameters:

Name	Type	Description	Default
provider	LocaleProvider	Provider instance used for translations.	required
force	bool	If True, allows reconfiguration even if already configured. Defaults to False to prevent accidental reconfiguration.	False

Raises:

Type	Description
ValueError	If provider is None.
RuntimeError	If configuration has already been performed and force is False.

detect_language(text, engine='lingua', fallback_language=None, confidence_threshold=None, config=None)

Detect the language for a single text string.

Parameters:

Name	Type	Description	Default
text	str	Input text to detect language from.	required
engine	str	Detection engine to use. Defaults to "lingua".	'lingua'
fallback_language	str | None	Fallback language code when detection confidence is low. Defaults to None.	None
confidence_threshold	float | None	Confidence threshold below which fallback is used. Defaults to None.	None
config	DetectionConfig | None	Detection configuration overriding defaults. Defaults to None.	None

Returns:

Name	Type	Description
DetectionResult	DetectionResult	Detected language and associated metadata.

Raises:

Type	Description
ValueError	If an unsupported engine is requested or configuration overrides are invalid.

get_locale()

Retrieve the locale for the current thread.

Returns:

Name	Type	Description
str	str	Active locale identifier in the calling thread.

Raises:

Type	Description
RuntimeError	If no locale has been configured for the current thread.

get_or_create_transliterator(target_script, source_script=None)

Return an ICU transliterator for the requested script pair.

Parameters:

Name	Type	Description	Default
target_script	str | SupportedScripts	Desired output script.	required
source_script	str | SupportedScripts | None	Optional source script hint. Defaults to None, which causes ICU to auto-detect the source script.	None

Returns:

Type	Description
Transliterator	icu.Transliterator: ICU transliterator instance configured for the requested scripts.

Raises:

Type	Description
ValueError	If either script is unsupported.
RuntimeError	If creating the ICU transliterator fails.

locale_context(locale)

Return a context manager that temporarily activates locale.

Example

with locale_context("fr"):
    print(_("Hello"))

Parameters:

Name	Type	Description	Default
locale	str	Locale identifier to use inside the context block.	required

Returns:

Name	Type	Description
_LocaleContextManager	_LocaleContextManager	Context manager handling locale switching.

Raises:

Type	Description
ValueError	If locale is empty or whitespace.
LocaleNotFoundError	If the locale is unavailable while strict mode is enabled.

normalize_and_strip(text, form=NormalizationForm.NFC)

Normalize text and remove diacritics in one operation.

Examples:

normalize_and_strip("café")  # "cafe"

Parameters:

Name	Type	Description	Default
text	str | Sequence[str | None] | None	A single string, sequence of strings, or None to process.	required
form	NormalizationForm | str	Unicode normalization form applied before stripping. Defaults to NormalizationForm.NFC.	NFC

Returns:

Type	Description
str | list[str]	The normalized text with diacritics removed, preserving the input type.

normalize_text(text, form=NormalizationForm.NFC)

Normalize Unicode text to a canonical or compatibility form.

Normalization Forms

Unicode defines four forms: NFD (canonical decomposition), NFC (canonical composition), NFKD (compatibility decomposition), and NFKC (compatibility composition).

1. "café" becomes "café" in NFD and stays "café" in NFC.
2. "Äffin" becomes "Äffin" in NFKD and becomes "Äffin" in NFKC.

Examples:

normalize_text("café", form=NormalizationForm.NFD)  # "café"
normalize_text("café", form=NormalizationForm.NFC)  # "café"
normalize_text("Äffin", form=NormalizationForm.NFKD)  # "Äffin"
normalize_text("Äffin", form=NormalizationForm.NFKC)  # "Äffin"

Parameters:

Name	Type	Description	Default
text	str | Sequence[str | None] | None	A single string, sequence of strings, or None to normalize.	required
form	NormalizationForm | str	Unicode normalization form. Defaults to NormalizationForm.NFC.	NFC

Returns:

Type	Description
str | list[str]	str | list[str]: The normalized text, preserving the input type str or list[str]). None inputs are converted to empty strings.

remove_diacritics(text)

Remove combining diacritical marks from Unicode text.

Examples:

remove_diacritics("café")  # "cafe"

Parameters:

Name	Type	Description	Default
text	str | Sequence[str | None] | None	A single string, sequence of strings, or None from which to remove diacritics.	required

Returns:

Type	Description
str | list[str]	str | list[str]: The text with diacritics removed, preserving the input type. None inputs are converted to empty strings.

set_locale(locale)

Set the locale for the current thread.

Parameters:

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

Raises:

Type	Description
ValueError	If locale is empty or only whitespace.
LocaleNotFoundError	If the locale is unavailable while strict mode is enabled.

to_ascii(text, preserve_case=True)

Convert arbitrary Unicode text to an ASCII representation.

Examples:

from gllm_intl.text.transliteration import to_ascii

to_ascii("Привет мир")
# "Privet mir"

Parameters:

Name	Type	Description	Default
text	str	Input text, potentially containing non-ASCII characters.	required
preserve_case	bool	Whether to keep the output casing as-is. When False the result is converted to lowercase for case-insensitive comparisons. Defaults to True.	True

Returns:

Name	Type	Description
str	str	ASCII-only text suitable for search indexing and slug generation.

transliterate(text, target_script, source_script=None)

Transliterate text between supported writing systems.

Examples:

from gllm_intl.text.transliteration import transliterate

transliterate("Привет мир", "LATIN", "CYRILLIC")
# "Privet mir"

Parameters:

Name	Type	Description	Default
text	str	Source text to convert. Empty strings return empty strings.	required
target_script	str | SupportedScripts	Desired output script. Must belong to SupportedScripts.	required
source_script	str | SupportedScripts | None	Optional source script hint. Defaults to None, which causes ICU to auto-detect the source script.	None

Returns:

Name	Type	Description
str	str	Transliterated text. Characters without matches remain unchanged.

Raises:

Type	Description
ValueError	If provided scripts are unsupported.
RuntimeError	If ICU transliterator creation fails.