Localization Contract

Amvionlie localization is a Core-owned system. Addons may provide language files, but Core discovers, parses, normalizes, and serves the strings.

Addon language files live at:

addons/{addon_key}/languages/{locale}/{namespace}.php

A file such as:

addons/ticket_support/languages/en_US/admin.php

is exposed through keys shaped like:

ticket_support.admin.some_key

Language files may use the governed PHP file header, including `declare(strict_types=1);` and the `HC_ACCESS` guard, before returning a flat string array. Core must parse that governed shape correctly.

Rules:

• Keep translatable UI copy in language files when the addon has a language namespace.
• Runtime fallbacks are safety rails only, not the source of truth.
• Do not duplicate route, permission, or schema truth into language files.
• Do not make language files execute logic or query storage.
• Add smoke coverage when a localization bug is fixed, especially if fallback text masked the failure.

When testing localization, verify the actual language file loads. A screen showing the right words is not enough if it is only showing fallback strings. That path looks fine until the next translation pass, and then everyone has a tiny paperwork thunderstorm.