# Localization

The Localization module resolves a language for each request, stores the selected language, loads translation resources, and exposes a translation contract to application services.

# Components and request flow

LanguageResolver selects a language and returns a LanguageMatch with language and path. Router stores the selected language in CurrentLanguage, dispatches LocaleChangedEvent, and adds language as a request attribute.

TranslationLoader loads translation resources. Translation implements TranslationInterface. LocalizationServiceProvider registers localization services. Applications can subscribe to locale-change events.

# Use translations

final class PageService
{
    public function __construct(
        private readonly TranslationInterface $translation
    ) {}

    public function title(): string
    {
        return $this->translation->trans('page.title');
    }
}

Translation file discovery, supported languages, fallback behavior, and resource paths are application configuration. Check the active provider and environment settings before adding files.

Keep keys stable and provide all configured languages or a deliberate fallback. Do not assume every key exists in every language catalog.

# Placeholders and translated validation

Pass replacement data as the second argument to trans():

$message = $translation->trans('welcome.message', ['name' => 'Alex']);

Use named placeholders in catalogs and keep the same key and placeholder names across language files. The Validator can receive a translation service so validation messages follow the same language configuration. A platform may also expose language selection in templates, but helpers and persistence behavior are application-specific.

# Language resolution

The framework has a LanguageResolver, CurrentLanguage, TranslationLoader, and LocalizationServiceProvider. In the HTTP pipeline the router can store the selected locale in current-language state, attach it to request attributes, and dispatch LocaleChangedEvent. Which languages and catalog directories are active is configured by the consuming application.