Core

Localization

Resolving della locale corrente, caricamento delle traduzioni, fallback strategy e applicazione della lingua durante il runtime.

Overview

Localization is registered by LocalizationServiceProvider. Primary runtime contracts are TranslatorInterface and LocaleResolverInterface. Router and URL generation can use localization URL strategy config for localized route names and prefixes.

Configuration

Localization is configured in app/Config/Localization.yaml. YAML is only the app-level source format; the framework still maps it into typed LocalizationConfigDefinition and resolves runtime LocalizationConfig.

example.php
module: localization
config:
  default_locale: cs
  fallback_locale: en
  supported_locales:
    - cs
    - en
  url:
    enabled: true
    include_default_locale: false
    localized_route_name_prefix: localized.
    locale_parameter: locale
    route_prefix: /{locale}

Translator behavior

FileTranslator loads translation groups from framework files (src/Language/{locale}/{group}.php) and overlays app files (app/Language/{locale}/{group}.php). Key lookup order for get() is: resolved locale -> fallback locale -> raw key string.

Fallbacks and missing keys

If translation key is missing in both resolved locale and fallback locale, translator returns the original key (for example homepage.title).

Locale resolution

LocaleResolver resolves locale in this order: runtime translator locale override, then LocalizationConfig::$defaultLocale, then LocalizationConfig::$fallbackLocale; all must be inside LocalizationConfig::$supportedLocales (non-empty list). Invalid config throws runtime exception.

Controller usage

Controllers can use translator directly ($this->translator()->get(...)) or convenience method ($this->trans(...)).

example.php
$title = $this->translator()->get('home.hero.title');
$button = $this->trans('home.hero.primary_cta');

Dependency injection usage

In services, inject TranslatorInterface (or LocaleResolverInterface when only locale resolution is needed).

example.php
use Lemonade\Framework\Localization\TranslatorInterface;

public function __construct(
    private readonly TranslatorInterface $translator,
) {}

View usage

Views should use the explicit $helpers object shared by the view lifecycle.

example.php
<?= e($helpers->lang('home.hero.title')) ?>
<?= e($helpers->lang('home.hero.primary_cta')) ?>

Localized routes and URLs

Router supports localizedGroup(...). During bootstrap, framework configures localized route name prefix, locale parameter and localized path prefix from LocalizationConfig::$url. UrlGenerator::localizedRoute(...) uses LocaleUrlStrategyInterface and falls back to non-localized route when localized variant does not exist.

example.php
$router->localizedGroup(static function (Router $router): void {
    $router->getNamed('home', '/', 'HomeController@index');
});

$url = $this->url()->localizedRoute('home');