orionis.localization.Translator

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class Translator(ITranslator): (source)

Constructor: Translator(locale, fallback, loader, repository)

View In Hierarchy

Resolve translation lines for the active locale.

The translator performs O(1) lookups against the in-memory repository, falls back to the configured fallback locale, applies style :name parameter replacement, and selects pluralized segments through choice.

Notes

The provider binds a single instance for the whole process and the class uses no lock, so setLocale, missing, reload, forget and flush are global side effects visible to every concurrent task. Pass an explicit locale to get, has or choice to select a language for a single call instead.

Method	`__applyReplacements`	Substitute placeholders into a translation line.
Method	`__asNumber`	Parse a plural condition token into a number.
Method	`__assertLocale`	Validate a locale code and return it unchanged.
Method	`__init__`	Initialize the translator with its locales and collaborators.
Method	`__matchesBound`	Evaluate one bound of an explicit range condition.
Method	`__matchExplicitSegment`	Select the plural segment whose explicit condition matches.
Method	`__matchPluralSegment`	Select the plural segment through positional rules.
Method	`__resolveMissing`	Resolve the line for a missing translation key.
Method	`__stripCondition`	Remove a leading explicit condition from a plural segment.
Method	`availableLocales`	Return every locale with at least one translation source.
Method	`choice`	Retrieve a pluralized translation line based on count.
Method	`flush`	Discard every cached translation map.
Method	`forget`	Discard the cached translations for a single locale.
Method	`get`	Retrieve the translation line registered under key.
Method	`getLocale`	Return the active locale.
Method	`has`	Determine whether a translation exists for key.
Method	`missing`	Register a handler invoked when a translation key is missing.
Method	`reload`	Discard cached translations so they are re-read from disk.
Method	`setLocale`	Change the active locale at runtime.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_fallback`	Undocumented
Instance Variable	`_loader`	Undocumented
Instance Variable	`_locale`	Undocumented
Instance Variable	`_missing`	Undocumented
Instance Variable	`_repository`	Undocumented

def __applyReplacements(self, line: str, replace: dict[str, object]) -> str: (source) ¶

Substitute placeholders into a translation line.

Each parameter replaces its :key, :Key, and :KEY variants with the raw, capitalized, and uppercased value respectively. Longer parameter names are applied first so they are never shadowed by shorter prefixes.

Parameters
line:`str`	Translation line containing the placeholders.
replace:`dict[str, object]`	Mapping of placeholder name to replacement value.

Returns
`str`	Line with every placeholder substituted.

def __asNumber(self, raw: str) -> float | None: (source) ¶

Parse a plural condition token into a number.

Parameters
raw:`str`	Condition token extracted from a plural segment.

Returns
`float \| None`	Numeric value, or `None` when the token is not numeric.

def __assertLocale(self, locale: str) -> str: (source) ¶

Validate a locale code and return it unchanged.

Parameters
locale:`str`	Locale code to validate.

Returns
`str`	The validated locale code.

Raises
`InvalidLocaleException`	If the locale is empty, malformed, or unsafe for path use.

def __init__(self, *, locale: str, fallback: str, loader: ITranslationLoader, repository: ITranslationRepository): (source) ¶

Initialize the translator with its locales and collaborators.

Parameters
locale:`str`	Active locale code.
fallback:`str`	Locale used when a translation is missing.
loader:`ITranslationLoader`	Loader used to discover the available locales.
repository:`ITranslationRepository`	In-memory cache resolving translation maps per locale.

Returns
`None`	Undocumented

Raises
`InvalidLocaleException`	If either locale code is malformed.

def __matchesBound(self, raw: str, count: int, *, lower_bound: bool) -> bool: (source) ¶

Evaluate one bound of an explicit range condition.

Parameters
raw:`str`	Bound token, either a number or the `*` wildcard.
count:`int`	Quantity evaluated against the bound.
lower_bound:`bool`	Whether the token is the lower bound of the range.

Returns
`bool`	True when the count satisfies the bound.

def __matchExplicitSegment(self, segments: list[str], count: int) -> str | None: (source) ¶

Select the plural segment whose explicit condition matches.

Parameters
segments:`list[str]`	Plural segments split from the raw translation line.
count:`int`	Quantity evaluated against each condition.

Returns
`str \| None`	Matching segment body, or `None` when no explicit condition applies.

def __matchPluralSegment(self, segments: list[str], count: int) -> str: (source) ¶

Select the plural segment through positional rules.

Parameters
segments:`list[str]`	Plural segments split from the raw translation line.
count:`int`	Quantity used to pick singular or plural form.

Returns
`str`	Selected segment stripped of any explicit condition.

def __resolveMissing(self, key: str, locale: str) -> str: (source) ¶

Resolve the line for a missing translation key.

Parameters
key:`str`	Translation key that produced no match.
locale:`str`	Locale in which the key was requested.

Returns
`str`	Replacement line provided by the handler, or the key itself.

def __stripCondition(self, segment: str) -> str: (source) ¶

Remove a leading explicit condition from a plural segment.

Parameters
segment:`str`	Raw plural segment possibly prefixed by a condition.

Returns
`str`	Segment body without its condition, trimmed of whitespace.

def availableLocales(self) -> tuple[str, ...]: (source) ¶

overrides orionis.localization.contracts.ITranslator.availableLocales

Return every locale with at least one translation source.

Returns
`tuple[str, ...]`	Sorted locale codes discovered in the language path.

def choice(self, key: str, count: int, locale: str | None = None, **replace: object) -> str: (source) ¶

overrides orionis.localization.contracts.ITranslator.choice

Retrieve a pluralized translation line based on count.

Segments are separated by | and may declare explicit conditions such as {0}, {1} or ranges [2,*]. When no explicit condition matches, the first segment is used for a count of one and the second segment otherwise. The :count placeholder is always available in the selected segment.

Parameters
key:`str`	Translation key containing the pluralized segments.
count:`int`	Quantity used to select the proper segment. The value is used as received: explicit conditions compare it against their numeric bounds and the positional rule tests `count == 1`. No coercion or validation is applied, so a non-numeric quantity propagates the comparison `TypeError` raised by Python.
locale:`str \| None, optional`	Locale to translate into, or `None` for the active locale.
**replace:`object`	Placeholder values substituted into the selected segment.

Returns
`str`	Pluralized and interpolated translation line.

Raises
`InvalidLocaleException`	If an explicit locale is malformed.

def flush(self): (source) ¶

overrides orionis.localization.contracts.ITranslator.flush

Discard every cached translation map.

Returns
`None`	Undocumented

def forget(self, locale: str) -> bool: (source) ¶

overrides orionis.localization.contracts.ITranslator.forget

Discard the cached translations for a single locale.

Parameters
locale:`str`	Locale code whose cache entry must be removed.

Returns
`bool`	True when an entry was removed, False otherwise.

Raises
`InvalidLocaleException`	If the locale is malformed.

def get(self, key: str, locale: str | None = None, **replace: object) -> str: (source) ¶

overrides orionis.localization.contracts.ITranslator.get

Retrieve the translation line registered under key.

The lookup order is the requested locale first, then the fallback locale, and finally the key itself when no translation exists. Placeholders in the :name form are substituted with the values provided in replace.

Parameters
key:`str`	Translation key, either a literal source text or a dot-notated grouped key such as `validation.required`.
locale:`str \| None, optional`	Locale to translate into, or `None` for the active locale.
**replace:`object`	Placeholder values substituted into the resolved line.

Returns
`str`	Translated line, or the key itself when missing.

Raises
`InvalidLocaleException`	If an explicit locale is malformed.

def getLocale(self) -> str: (source) ¶

overrides orionis.localization.contracts.ITranslator.getLocale

Return the active locale.

Returns
`str`	Locale code currently in use.

def has(self, key: str, locale: str | None = None, *, fallback: bool = True) -> bool: (source) ¶

overrides orionis.localization.contracts.ITranslator.has

Determine whether a translation exists for key.

Parameters
key:`str`	Translation key to check.
locale:`str \| None, optional`	Locale to inspect, or `None` for the active locale.
fallback:`bool, optional`	Whether the fallback locale is also inspected.

Returns
`bool`	True when a translation line is registered for the key.

Raises
`InvalidLocaleException`	If an explicit locale is malformed.

def missing(self, handler: MissingKeyHandler | None): (source) ¶

overrides orionis.localization.contracts.ITranslator.missing

The handler receives the key and the locale, and may return a replacement line. When it returns None the key itself is used as the translation.

Parameters
handler:`MissingKeyHandler \| None`	Callable invoked on missing keys, or `None` to remove the current handler.

Returns
`None`	Undocumented

def reload(self, locale: str | None = None): (source) ¶

overrides orionis.localization.contracts.ITranslator.reload

Discard cached translations so they are re-read from disk.

Parameters
locale:`str \| None, optional`	Locale to reload, or `None` to reload every locale.

Returns
`None`	Undocumented

Raises
`InvalidLocaleException`	If an explicit locale is malformed.

def setLocale(self, locale: str): (source) ¶

overrides orionis.localization.contracts.ITranslator.setLocale

Change the active locale at runtime.

Parameters
locale:`str`	Locale code to activate.

Returns
`None`	Undocumented

Raises
`InvalidLocaleException`	If the locale is malformed.

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.localization.contracts.ITranslator.__slots__

Undocumented

_fallback = (source) ¶

Undocumented

_loader = (source) ¶

Undocumented

_locale = (source) ¶

Undocumented

_missing: MissingKeyHandler | None = (source) ¶

Undocumented

_repository = (source) ¶

Undocumented