cadrumo.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:
CoreErrorRaised 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¶
- exception MissingTranslationError(*, key, locale)[source]¶
Bases:
CoreErrorRaised in strict-missing-key mode when a catalogue does not carry a key.
Indicates that a
tr()call site names a key absent from the locale, or one whose value is the key itself (the scaffold placeholder for “not translated yet”). Outside strict mode both cases fall back to a humanised label, so a missing string never aborts a filing.- Variables:
key – The locale translation key that could not be resolved.
locale – The locale whose catalogue was consulted.
- Parameters:
- Return type:
None
- code¶
- 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.i18ncan read profile-level language preferences without importing application modules directly.
- normalise_supported_language(value)[source]¶
Return the supported-language token
valuenames, orNone.
- output_language()[source]¶
Resolve the operator-facing output language.
An explicit
cadrumo_output_languagevalue on the active Settings (env var,override_settingsblock, or.envfile) wins for one-off sessions and automation. Otherwise the active profile’soutput.languagekey is used. The settings default remains the final fallback and defaults to Spanish for a clean install.- Return type:
- Returns:
The resolved ISO 639-1 language code.
- clear_output_language_cache()[source]¶
Invalidate cached language resolution after profile/config writes.
- Return type:
- clear_output_language_cache_for_settings_override()[source]¶
Invalidate at an
override_settingsboundary the resolver does not own.override_settingsinvalidates at both of its boundaries because the cache keys an override block byid(override)and a GC’d block’s address can be reused. That is right for every block an operator or a command opens, and wrong for exactly one: resolving the active profile’s language scopes its own read withoverride_settings(cadrumo_active_profile=...), so the resolution invalidated the very entry it was about to store.The version is part of the cache key, so each resolution left the next call keyed to a dead version — a cache that could never serve a hit while a bucket session was bound. Every
tr()then paid a full encrypted profile read and threeSettingsconstructions, which is roughly 44 ms each on Windows, where a construction resolves 28 configured paths. One manager repaint resolves a few hundred strings, so re-wording the page after a language change cost around thirteen seconds.Suppressing the boundary only while a resolution is in flight is what separates the two cases: the profile-write, registration, and CLI-init invalidations all go through
clear_output_language_cache()and are never suppressed, so a write that genuinely moves the language is still seen. The flag is aContextVar, so a resolution running on one task cannot silence another’s boundary, and a thread that never resolved sees the default and invalidates normally.- Return type:
- tr(translation_key, /, **kwargs)[source]¶
Render an abstract translation key in the configured output language.
- Parameters:
- Return type:
- Returns:
The translated string.
- Raises:
UnmatchedPlaceholderError – When strict-placeholder mode is active and the rendered string still contains an un-interpolated
{name}token.MissingTranslationError – When strict-missing-key mode is active, the catalogue does not carry
translation_key, and no explicitdefaultwas supplied.
- extract_placeholders(value)[source]¶
Return interpolation names consumed by the production renderer.
The renderer first replaces
%{name}tokens and then delegates{name}tokens tostr.format(). Parsing the second form throughstring.Formatterpreserves conversions and specifications. Root kwargs consumed by attribute and index fields are returned, and nested replacement fields inside format specifications are inspected recursively. Escaped braces and brace-delimited prose are excluded. For malformed strings, independently valid fields are recovered without representing the malformed format string itself as complete or renderable.
- override_locales_root(root)[source]¶
Resolve catalogues from
rootinstead of the packaged resources.The renderer’s miss semantics — an absent key and a key-echo value are both misses (
_lookup_translation()) — can only be exercised against a catalogue that carries the defect, and the shipped catalogues are gated echo-free. This override is the sanctioned seam for pointing resolution at a fixture catalogue, mirroringoverride_settings(); the packaged resources stay the sole source otherwise.
- lookup_translation(translation_key, /, *, locale)[source]¶
Return one authored locale scalar without humanising a missing value.
Noneand the catalogue scaffold conventionvalue == keyboth mean that the selected locale has no authored value. Domain resolvers use this primitive when they own a stricter fallback policy than the operator-facingtr()convenience surface.