aeat.locales.manager module

Locale file management: loading, scaffolding, and structural health checks.

LocaleManager owns codebase translation-key discovery and locale YAML updates. StrictUniqueKeyLoader enforces parse-time duplicate-key rejection, while LocaleNode documents the recursive locale-tree shape shared by the manager and parity tests.

exception LocaleError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Raised on locale management and parsing errors.

Parameters:

• message (str | None)

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

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

class StrictUniqueKeyLoader(stream)

Bases: SafeLoader

YAML loader that raises an error on duplicate keys.

construct_mapping(node, deep=False)

Construct a mapping node, raising LocaleError on duplicate keys.

Parameters:

• node (MappingNode) – The YAML mapping node to construct.

• deep (bool) – Whether to construct values recursively before returning.

Return type:

dict[Hashable, Any]

Returns:

A plain dict of the mapping’s key-value pairs.

Raises:

LocaleError – When a duplicate key is found in the mapping node.

class LocaleManager(src_dir, locales_dir)

Bases: object

API for managing locale files, scaffolding, and structural health.

Parameters:

• src_dir (Path)

• locales_dir (Path)

get_codebase_keys()

Extract all concrete dotted translation keys from the codebase.

Combines three discovery paths:

1. Regex scanner — tr("…") / t("…") literal call sites.

2. AST scanner — programmatic emissions such as WizardValidationError("wizard.errors.select_unknown"), message_key= kwargs, and build_entry portal keys.

3. F-string registry — bounded f-string patterns whose value sets are fully known at import time (e.g. wizard choice labels keyed by enum values). See locales._fstring_registry.

Dynamic namespaces (open-ended f-string and concatenation forms) are returned by get_codebase_namespaces() and checked through a separate parity assertion that verifies at least one concrete locale key exists under each declared prefix.

Return type:

set[str]

get_codebase_namespaces()

Extract dynamic-namespace markers (<prefix>.*) from the codebase.

Returns every prefix discovered through f-string or string concatenation patterns whose tail is computed at runtime. Each marker passes the parity check when at least one concrete locale key starts with its prefix.

Return type:

set[str]

get_yaml_keys(d, current_path='')

Recursively extract all dot-notated keys from a nested dictionary.

Return type:

set[str]

Parameters:

• d (dict[str, LocaleNode])

• current_path (str)

load_locale(path)

Load a locale YAML file strictly, failing on duplicates.

Return type:

dict[str, TypeAliasType]

Parameters:

path (Path)

scaffold()

Parse codebase, generate locale files, auto-sort, and prune extra keys.

Return type:

None

set_locale_value(locale, dotted_key, value)

Set one locale leaf while preserving the YAML layout.

Return type:

Path

Parameters:

• locale (str)

• dotted_key (str)

• value (str)

remove_locale_value(locale, dotted_key)

Remove one existing locale leaf while preserving the YAML layout.

Return type:

Path

Parameters:

• locale (str)

• dotted_key (str)