orionis.localization.TranslationLoader

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 TranslationLoader(ITranslationLoader): (source)

Constructor: TranslationLoader(path)

View In Hierarchy

Load translation sources from the configured language path.

The loader reads root JSON files ({path}/{locale}.json) whose keys are the literal source texts, and grouped JSON files ({path}/{locale}/{group}.json) flattened with dot notation such as validation.required. Decoding is performed with msgspec for maximum throughput. The loader holds no cache: that concern belongs to the repository.

Notes

Translation files are read as raw bytes and decoded as UTF-8 JSON. A source stored in any other encoding raises TranslationSyntaxException, like any other unusable payload.

Method	`__flatten`	Flatten a nested translation object into dot-notated keys.
Method	`__init__`	Initialize the loader with the language directory.
Method	`__readFile`	Decode a single translation file with msgspec.
Method	`availableLocales`	Discover every locale with at least one translation source.
Method	`load`	Load every translation available for locale.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_path`	Undocumented

def __flatten(self, payload: dict[str, object], prefix: str, target: TranslationMap): (source) ¶

Flatten a nested translation object into dot-notated keys.

Parameters
payload:`dict[str, object]`	Nested translation object to flatten.
prefix:`str`	Dot-notated prefix accumulated so far.
target:`TranslationMap`	Mutable mapping receiving the flattened entries.

Returns
`None`	Undocumented

def __init__(self, path: Path): (source) ¶

Initialize the loader with the language directory.

Parameters
path:`Path`	Absolute directory containing the translation sources.

Returns
`None`	Undocumented

def __readFile(self, file: Path) -> dict[str, object]: (source) ¶

Decode a single translation file with msgspec.

Parameters
file:`Path`	Absolute path of the JSON file to decode.

Returns
`dict[str, object]`	Decoded JSON object.

Raises
`TranslationFileNotFoundException`	If the file does not exist.
`TranslationSyntaxException`	If the payload is not UTF-8 encoded, is invalid JSON, or its root element is not an object.

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

overrides orionis.localization.contracts.ITranslationLoader.availableLocales

Discover every locale with at least one translation source.

Returns
`tuple[str, ...]`	Sorted locale codes discovered from root JSON files and grouped directories inside the language path.

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

overrides orionis.localization.contracts.ITranslationLoader.load

Load every translation available for locale.

Grouped files are merged first and root JSON entries are merged last so literal-text keys take precedence on collision.

Parameters
locale:`str`	Locale code whose translation sources must be read.

Returns
`TranslationMap`	Flat mapping of translation key to translated text. An empty mapping is returned when no source exists.

Raises
`TranslationSyntaxException`	If a translation file is not UTF-8 encoded, contains invalid JSON, or its root element is not an object.

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

overrides orionis.localization.contracts.ITranslationLoader.__slots__

Undocumented

_path = (source) ¶

Undocumented