Languages and locales

Tools\Utility\Language matches supported languages against the browser's Accept-Language header. Changing a configuration value does not change CakePHP's active locale; call I18n::setLocale() explicitly.

Configure supported languages

Add this entry to the array returned by config/app.php, preserving the existing configuration:

'Config' => [
    'defaultLanguage' => 'en',
    'allowedLanguages' => [
        'en' => ['locale' => 'en_US', 'name' => 'English'],
        'de' => ['locale' => 'de_DE', 'name' => 'Deutsch'],
    ],
],

The language key is used in switch links. The locale controls translations and regional formatting.

Select the locale for each request

In the existing AppController::initialize() method, after parent::initialize(), add the following. Import Cake\Core\Configure, Cake\I18n\I18n, and Tools\Utility\Language at the top of the controller.

$allowed = (array)Configure::read('Config.allowedLanguages');
$locale = $this->getRequest()->getSession()->read('Config.language');
if (!is_string($locale) || !in_array($locale, array_column($allowed, 'locale'), true)) {
    $language = Language::findFirstMatch(array_keys($allowed), [], true);
    $default = Configure::read('Config.defaultLanguage');
    $locale = $allowed[$language]['locale'] ?? $allowed[$default]['locale'] ?? I18n::getLocale();
}
I18n::setLocale($locale);

The session takes precedence over the browser preference. The configured default applies when no supported language matches. Keep the controller's other initialization code.

Add a language switch

The library installation disables all Tools routes. To enable only the language endpoint, import Cake\Routing\RouteBuilder in config/routes.php and add this inside its existing returned routing closure:

$routes->plugin('Tools', ['path' => '/tools'], function (RouteBuilder $builder): void {
    $builder->connect('/language/{language}', ['controller' => 'ShuntRequest', 'action' => 'language'])
        ->setPass(['language'])
        ->setMethods(['POST']);
});

In a template, render POST links using the application's Form helper:

use Cake\Core\Configure;

foreach ((array)Configure::read('Config.allowedLanguages') as $language => $settings) {
    echo $this->Form->postLink($settings['name'], [
        'prefix' => false,
        'plugin' => 'Tools',
        'controller' => 'ShuntRequest',
        'action' => 'language',
        $language,
    ]);
}

The endpoint rejects languages outside Config.allowedLanguages, stores the selected locale in the session, and redirects back. Its controller extends the application's AppController, so application authentication and authorization controls apply. Allow access to the switch where appropriate for the application.

Language in URLs

A session switch does not add language prefixes to other routes. Applications needing paths such as /de/articles must define those routes, select a locale from the parsed language parameter, and include that parameter when generating links and redirects. This is application routing policy rather than an automatic Tools feature.