aeat.core.i18n._render module

Translation rendering primitives shared across the codebase.

The application and adapter layers import tr() from here so they can render translatable keys without reaching into the CLI entrypoints. python-i18n is initialised lazily on first call.

exception UnmatchedPlaceholderError(*, key, name, rendered)[source]

Bases: CoreError

Raised in strict-placeholder mode when a locale value retains a {name} token.

Indicates that a tr() call site supplies a key whose locale value contains a placeholder not covered by the supplied kwargs (ORPHAN), or that the locale value was never interpolated at all.

Variables:

  • key – The locale translation key that triggered the error.

  • name – The placeholder name that survived substitution.

  • rendered – The partially-rendered string at the time of detection.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
register_profile_language_resolver(fn)[source]

Register a callback that resolves the active-profile output language.

The application layer calls this once at startup so core.i18n can read profile-level language preferences without importing application modules directly.

Return type:

None

Parameters:

fn (Callable[[], str | None])

output_language()[source]

Resolve the operator-facing output language.

An explicit aeat_output_language value on the active Settings (env var, override_settings block, or .env file) wins for one-off sessions and automation. Otherwise the active profile’s output.language key is used. The settings default remains the final fallback and defaults to Spanish for a clean install.

Return type:

str

Returns:

The resolved ISO 639-1 language code.

clear_output_language_cache()[source]

Invalidate cached language resolution after profile/config writes.

Return type:

None

tr(translation_key, /, **kwargs)[source]

Render an abstract translation key in the configured output language.

Parameters:

  • translation_key (str) – The abstract namespace key to render (e.g., "cli.auth.purpose"). Positional-only so callers can pass interpolation kwargs named key without collision.

  • **kwargs (object) – Interpolation arguments for python-i18n.

Return type:

str

Returns:

The translated string.

Raises:

UnmatchedPlaceholderError – When strict-placeholder mode is active and the rendered string still contains an un-interpolated {name} token.