README

Yii Framework

Locale URLs

Language detection, persistence, and locale-aware URLs for Yii2 applications

Features

Worker-mode requirements (sessions, cookies, event handlers) are listed in the configuration guide.

Installation

composer require yii2-extensions/localeurls:^0.2

Quick start

How it works

Detects the language from the URL path (/es/about sets Spanish).
Falls back to the persisted language, then to browser headers or GeoIP, then to the default language.
Adds the language code to generated URLs, except for the default language (see enableDefaultLanguageUrlCode).
Remembers the choice in session and cookie.

Basic configuration

Replace the urlManager component in config/web.php. The application language is the default language, which has no code in the URL; the defaultLanguage property of the manager sets it explicitly.

<?php

declare(strict_types=1);

use yii2\extensions\localeurls\UrlLanguageManager;

return [
    'language' => 'en',
    'components' => [
        'urlManager' => [
            'class' => UrlLanguageManager::class,
            'languages' => ['en', 'es', 'fr', 'de'],
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'rules' => [
                '' => 'site/index',
                '<controller:\w+>/<action:\w+>' => '<controller>/<action>',
            ],
        ],
    ],
];

Automatic URL generation

<?php

declare(strict_types=1);

use yii\helpers\Url;

// Current language `en`, the default language.
Url::to(['site/about']); // /site/about
// Current language `es`, set by a request such as /es/site/index.
Url::to(['site/about']); // /es/site/about
// Another language.
Url::to(['site/contact', 'language' => 'fr']); // /fr/site/contact

Documentation

Practical guides and examples for language-aware URLs and worker isolation.

📚 Installation Guide
⚙️ Configuration Guide, including worker mode
💡 Usage Examples
🔄 Upgrade Guide
🧪 Testing Guide

The guides and the API reference generated from the PHPDoc in src/ are published at https://yii2-framework.github.io/docs/extensions/localeurls/.

AI assistance

AI agents: read the documentation index and fetch the Markdown version of a page by appending index.md to its URL. The AI agents guide covers skill installation, client setup and verification.

🤖 yii2-localeurls-configuration skill: Language URLs.
🧭 yii2-framework skill: Yii 22.0 application conventions.

The hosted documentation covers Yii 22.0. If it does not match the installed revision or is unavailable, use the repository guides, the skill source, the source PHPDoc and the changelog.