cadrumo.core.i18n.locale_catalogue module

Public locale-catalogue capture over one stable catalogue window.

This module owns the capture contract for the shipped translation catalogues. Catalogue loading, the scaffold-null suppression convention and key membership come from cadrumo.core.i18n.render. This owner fingerprints the exact shard bytes it observes; there is no second reader, cache, or routing rule.

The per-locale Spanish fallback and the modelo key-identity chain are owned by resolve_modelo_localization one layer above this one. This module deliberately does not reimplement them: it captures the catalogue state that resolver reads, so a caller can prove the value it resolved and the catalogue it resolved against belong to the same window.

See also

tr()

The operator-facing translation surface resolving through the same catalogue this module captures.

exception LocaleCatalogueCaptureError(message=None, *, context=None, translated_message=None)

Bases: CoreError

Raised when a locale catalogue cannot be captured over one stable window.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• translated_message (str | None)

Return type:

None

code

class LocaleCatalogueCapture(locale, translation_key, present, value, catalogue_digest, comparison_domain, generation)

Bases: object

One catalogue entry and the currentness coordinate it was read under.

present and value are exactly what the catalogue reader returned, including its convention that a scaffolded-but-untranslated key is present with no value. catalogue_digest is the shard fingerprint this entry was read under, published because a consumer assembling a locale summary has to name the catalogue it resolved against. The catalogue root and the process incarnation stay folded into the opaque comparison domain.

Parameters:

• locale (str)

• translation_key (str)

• present (bool)

• value (str | None)

• catalogue_digest (str)

• comparison_domain (str)

• generation (int)

locale: str

translation_key: str

present: bool

value: str | None

catalogue_digest: str

comparison_domain: str

generation: int

require_current(current)

Refuse a currentness comparison outside this owner process domain.

Return type:

LocaleCatalogueCapture

Parameters:

current (LocaleCatalogueCurrentCoordinate)

class LocaleCatalogueCurrentCoordinate(comparison_domain, generation)

Bases: object

Opaque same-process coordinate for one locale catalogue owner scope.

Parameters:

• comparison_domain (str)

• generation (int)

comparison_domain: str

generation: int

require_current(captured)

Require a capture from this exact owner scope and process incarnation.

Return type:

LocaleCatalogueCurrentCoordinate

Parameters:

captured (LocaleCatalogueCapture)

capture_locale_catalogue(translation_key, /, *, locale)

Read one catalogue entry over a window in which the catalogue did not move.

The shard digest is taken either side of the sole lookup_translation_entry() reader, so a catalogue rewritten mid-read is retried rather than published as an entry paired with a coordinate from another catalogue state.

Return type:

LocaleCatalogueCapture

Parameters:

• translation_key (str)

• locale (str)