# Locale URLs

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

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

## Features

![Feature Overview](/docs/_astro/features.D8dlVrqV.svg)

Worker-mode requirements (sessions, cookies, event handlers) are listed in the
[configuration guide](/docs/extensions/localeurls/configuration/index.md#worker-mode).

### Installation

```bash
composer require yii2-extensions/localeurls:^0.2
```

### Quick start

#### How it works

1. Detects the language from the URL path (`/es/about` sets Spanish).
2. Falls back to the persisted language, then to browser headers or GeoIP, then to the default language.
3. Adds the language code to generated URLs, except for the default language (see `enableDefaultLanguageUrlCode`).
4. 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
<?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
<?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](/docs/extensions/localeurls/installation/index.md)
- ⚙️ [Configuration Guide](/docs/extensions/localeurls/configuration/index.md), including
  [worker mode](/docs/extensions/localeurls/configuration/index.md#worker-mode)
- 💡 [Usage Examples](/docs/extensions/localeurls/examples/index.md)
- 🔄 [Upgrade Guide](https://github.com/yii2-extensions/localeurls/blob/main/UPGRADE.md)
- 🧪 [Testing Guide](/docs/extensions/localeurls/testing/index.md)

## AI assistance

AI agents: use the repository guides and source for the installed revision.
For a [documentation deployment](https://yii2-framework.github.io/docs/) with
`llms.txt`, read that index first. When Markdown export is enabled, append
`index.md` to a page URL. For Yii conventions, use the `yii2-framework` skill
from a local framework documentation checkout.

- 🤖 [yii2-localeurls-configuration skill](/docs/extensions/localeurls/agents/index.md): installation for
  Claude Code, Codex, and OpenCode.

If the hosted sources are unavailable, use the repository guides and locally available skills.

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)
[Join our Subreddit](https://www.reddit.com/r/Yii2/)
[Join on Telegram](https://t.me/yii_framework_in_english)

## Credits

This package started as a fork of [codemix/yii2-localeurls](https://github.com/codemix/yii2-localeurls).

## License

[License](https://github.com/yii2-extensions/localeurls/blob/main/LICENSE)

## Package

- Source code and issues: [yii2-extensions/localeurls](https://github.com/yii2-extensions/localeurls). Star the repository if the package is useful to you.
- Composer package: [yii2-extensions/localeurls](https://packagist.org/packages/yii2-extensions/localeurls).
- Changelog: [CHANGELOG.md](https://github.com/yii2-extensions/localeurls/blob/main/CHANGELOG.md).