ORIONIS API REFERENCE

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.

class documentation

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 using its native JSON decoder. 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 orionis.localization.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 __resolveSource Resolve a source inside the configured language directory.
Method availableLocales Discover every locale with at least one translation source.
Method load Load every translation available for locale.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _path Absolute directory containing the translation sources.
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:strDot-notated prefix accumulated so far.
target:orionis.localization.types.TranslationMapMutable mapping receiving the flattened entries.
Returns
NoneNo return value.
def __init__(self, path: Path): (source)

Initialize the loader with the language directory.

Parameters
path:pathlib.PathAbsolute directory containing the translation sources.
Returns
NoneNo return value.
def __readFile(self, file: Path) -> dict[str, object]: (source)

Decode a single translation file with msgspec.

Parameters
file:pathlib.PathAbsolute path of the JSON file to decode.
Returns
dict[str, object]Decoded JSON object.
Raises
orionis.localization.TranslationFileNotFoundExceptionIf the file does not exist.
orionis.localization.TranslationSyntaxExceptionIf the payload is not UTF-8 encoded, is invalid JSON, or its root element is not an object.
def __resolveSource(self, source: Path) -> Path: (source)

Resolve a source inside the configured language directory.

Parameters
source:pathlib.PathCandidate directory or JSON file, including symbolic links.
Returns
pathlib.PathResolved source within the configured directory.
Raises
orionis.localization.TranslationExceptionIf the source resolves outside the language directory.
def availableLocales(self) -> tuple[str, ...]: (source)

Discover every locale with at least one translation source.

Returns
tuple[str, ...]Sorted valid locale codes from sources resolving within the language directory. External links are omitted.
def load(self, locale: str) -> TranslationMap: (source)

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:strLocale code whose translation sources must be read.
Returns
orionis.localization.types.TranslationMapFlat mapping of translation key to translated text. An empty mapping is returned when no source exists.
Raises
orionis.localization.InvalidLocaleExceptionIf the locale code is malformed or contains path components.
orionis.localization.TranslationExceptionIf a source resolves outside the configured language directory.
orionis.localization.TranslationSyntaxExceptionIf a translation file is not UTF-8 encoded, contains invalid JSON, or its root element is not an object.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

Absolute directory containing the translation sources.