yii2-localeurls 189

Automatic locale/language management for URLs


Written in PHP by 10 contributors


Need Support?

we offer maintenance, support and development services for all our open source projects.

Contact Us

Yii2 Locale URLs

Build Status Latest Stable Version Total Downloads Latest Unstable Version HHVM Status License

Automatic locale/language management through URLs for Yii 2.

IMPORTANT: If you upgraded from version 1.0.* you have to modify your configuration. Please check the section on Upgrading below.


With this extension you can use URLs that contain a language code like:


You can also configure friendly names if you want:


The language code is automatically added whenever you create a URL, and read back when a URL is parsed. For best user experience the language is autodetected from the browser settings, if no language is used in the URL. The user can still access other languages, though, simply by calling a URL with another language code.

The last requested language is also persisted in the user session and in a cookie. So if the user tries to access your site without a language code in the URL, he'll get redirected to the language he had used on his last visit.

All the above (and more) is configurable of course.


Install the package through composer:

composer require codemix/yii2-localeurls

And then add this to your application configuration:

return [

    // ...

    'components' => [
        // ...

        // Override the urlManager component
        'urlManager' => [
            'class' => 'codemix\localeurls\UrlManager',

            // List all supported languages here
            // Make sure, you include your app's default language.
            'languages' => ['en-US', 'en', 'fr', 'de', 'es-*'],

        // ...

Now you're ready to use the extension.

Note: You can still configure custom URL rules as usual. Just ignore any language parameter in your URL rules as it will get removed before parsing and added after creating a URL.

Note 2: The language code will be removed from the pathInfo.

Mode of operation and configuration

Creating URLs

All created URLs will contain the code of the current application language. So if the language was detected to be de and you use:

<?php $url = Url::to(['demo/action']) ?>
<?= Html::a('Click', ['demo/action']) ?>

you'll get URLs like


To create a link to switch the application to a different language, you can explicitly add the language URL parameter:

<?= $url = Url::to(['demo/action', 'language' => 'fr']) ?>
<?= Html::a('Click', ['demo/action', 'language' => 'fr']) ?>

This will give you a URL like


Note: The URLs may look different if you use custom URL rules. In this case the language parameter is always prepended/inserted to the final relative/absolute URL.

If for some reason you want to use a different name than language for that URL parameter you can configure it through the languageParam option of the urlManager component.

Default Language

The default language is configured via the language parameter of your application configuration. You always have to include this language in the $languages configuration (see below).

By default the URLs for the default language won't contain any language code. For example:


If the site is accessed with URLs containing the default language code, the visitor gets redirected to the URLs without language code. For example if default language is fr:

/fr/            -> Redirect to /
/fr/some/page   -> Redirect to /some/page

If enableDefaultLanguageUrlCode is changed to true it's vice versa. The default language is now treated like any other configured language. Requests with URL that don't contain a language code are no longer accessible:

/               -> Redirect to /fr
/some/page      -> Redirect to /fr/some/page

Language Configuration

All languages including the default language must be configured in the languages parameter of the localeUrls component. You should list more specific language codes before the similar looking generic ones (i.e. 'en-US' before 'en'):

'languages' => ['en-US', 'en-UK', 'en', 'fr', 'de-AT', 'de'],

Note: If you use country codes, they should always be configured in upper case letters as shown above. The URLs will still always use lowercase codes. If a URL with an uppercase code like en-US is used, the user will be redirected to the lowercase en-us variant. The application language will always use the correct en-US code. If you don't want to redirect URLs with uppercase country code, you can set the keepUppercaseLanguageCode option to true.

If you want your URL to optionally contain any country variant you can also use a wildcard pattern:

'languages' => ['en-*', 'de-*'],

Now any URL that matches en-?? or de-?? could be used, like en-us or de-at. URLs without a country code like en and de will also still work:


The URLs with a country code will set the full ll-CC code as Yii language whereas the URLs with a language code only, will lead to ll as configured language.

Note: You don't need this if all you want is a fallback of de-AT to de for languages detected from the browser settings. See the section on Language Detection below.

You can also use friendlier names or aliases in URLs, which are configured like so:

'languages' => ['en', 'german' => 'de', 'br' => 'pt-BR'],
<?= Url::to(['demo/action', 'language' => 'de']) ?>

This will give you URLs like


and set the respective language to de or pt-PR if matched.


The last language a visitor has used will be stored in the user session and in a cookie. If the user visits your site again without a language code, he will get redirected to the stored language.

For example, if the user first visits:


then after some time comes back to one of the following URLs:

/some/page      -> Redirect to /de/some/page
/               -> Redirect to /de/

In the last case, dk will be stored as last language.

Persistence is enabled by default and can be disabled by setting enableLanguagePersistence to false in the localeUrls component.

You can modify other persistence settings with:

  • languageCookieDuration: How long in seconds to store the language information in a cookie. Set to false to disable the cookie.
  • languageCookieName: The name of the language cookie. Default is _language.
  • languageCookieOptions: Other options to set on the language cookie.
  • languageSessionKey: The name of the language session key. Default is _language.

Reset To Default Language

You'll notice, that there's one problem, if enableDefaultLanguageUrlCode is false (which is the default) and the user has e.g. stored de as last language. How can we now access the site in the default language? Because if we try / we'd be redirected to /de/.

The answer is simple: To create a reset URL, you explicitly include the language code for the default language in the URL. For example if default language is fr:

<?= Url::to(['demo/action', 'language' => 'fr']) ?>
/fr/demo/action -> Redirect to /demo/action

In this case, fr will first be stored as last used language before the user is redirected.

Language Detection

If a user visits your site for the first time and there's no language stored in session or cookie (or persistence is turned off), then the language is detected from the visitor's browser settings. If one of the preferred languages matches your language, it will be used as application language (and also persisted if persistence is enabled).

To disable this, you can set enableLanguageDetection to false. It's enabled by default.

If the browser language contains a country code like de-AT and you only have de in your $languages configuration, it will fall back to that language. Only if you've used a wildcard like de-* or have explicitly configured de-AT or an alias like 'at' => 'de-AT', the browser language including the country code will be used.

Let's look at an example configuration to better understand, how the $languages configuration affects language detection and the created URLs.

'languages' => [
  'at' => 'de-AT',

Now say a user visits your site for the first time. Depending on his browser settings, he will be directed to different URLs.

Accept-Language Header Resulting URL code Resulting Yii language
en, en-us, en-US, ... /en en
de-at, de-AT /at de-AT
de, de-de, de-DE, de-ch, ... /de de
pt-BR, pt-br /pt-br pt-BR
pt-PT, pt-pt /pt-pt pt-PT
Any other pt-CC code /pt-cc pt-CC
pt /pt pt

Excluding Routes / URLs

You may want to disable the language processing for some routes and URLs with the $ignoreLanguageUrlPatterns option:

    'ignoreLanguageUrlPatterns' => [
        '#^site/(login|register)#' => '#^(login|register)#',
        '#^api/#' => '#^api/#',

Both, keys and values are regular expressions. The keys are patterns that describe routes to exclude from language processing during URL creation, whereas the values are patterns to exclude during URL parsing.

Note: Keys and values don't necessarily have to relate to each other. It's just for convenience, that the configuration is combined into a single option.

Example Language Selection Widget

There's no widget for language selection included, because there are simply too many options for the markup and behavior of such a widget. But it's very easy to build. Here's the basic idea:

use Yii;
use yii\bootstrap\Dropdown;

class LanguageDropdown extends Dropdown
    private static $_labels;

    private $_isError;

    public function init()
        $route = Yii::$app->controller->route;
        $appLanguage = Yii::$app->language;
        $params = $_GET;
        $this->_isError = $route === Yii::$app->errorHandler->errorAction;

        array_unshift($params, '/' . $route);

        foreach (Yii::$app->urlManager->languages as $language) {
            $isWildcard = substr($language, -2) === '-*';
            if (
                $language === $appLanguage ||
                // Also check for wildcard language
                $isWildcard && substr($appLanguage, 0, 2) === substr($language, 0, 2)
            ) {
                continue;   // Exclude the current language
            if ($isWildcard) {
                $language = substr($language, 0, 2);
            $params['language'] = $language;
            $this->items[] = [
                'label' => self::label($language),
                'url' => $params,

    public function run()
        // Only show this widget if we're not on the error page
        if ($this->_isError) {
            return '';
        } else {
            return parent::run();

    public static function label($code)
        if (self::$_labels === null) {
            self::$_labels = [
                'de' => Yii::t('language', 'German'),
                'fr' => Yii::t('language', 'French'),
                'en' => Yii::t('language', 'English'),

        return isset(self::$_labels[$code]) ? self::$_labels[$code] : null;


Changes from 1.0. to 1.1.

If you upgrade from a 1.0.* version you'll have to modify your configuration. There no longer is a localeUrls component now. Instead everything was merged into our custom urlManager component. So you should move any configuration for the localeUrls component into the urlManager component.

Two options also have been renamed for more clarity:

  • enableDefaultSuffix is now enableDefaultLanguageUrlCode
  • enablePersistence is now enableLanguagePersistence

So if your configuration looked like this before:

return [
    'bootstrap' => ['localeUrls'],
    'components' => [
        'localeUrls' => [
            'languages' => ['en-US', 'en', 'fr', 'de', 'es-*'],
            'enableDefaultSuffix' => true,
            'enablePersistence' => false,
        'urlManager' => [
            'class' => 'codemix\localeurls\UrlManager',

you should now change it to:

return [
    'components' => [
        'urlManager' => [
            'class' => 'codemix\localeurls\UrlManager',
            'languages' => ['en-US', 'en', 'fr', 'de', 'es-*'],
            'enableDefaultLanguageUrlCode' => true,
            'enableLanguagePersistence' => false,

43 other PHP projects

phpwkhtmltopdfPHP 716

A slim PHP wrapper around wkhtmltopdf with an easy to use and clean OOP interface

php-pdftkPHP 213

A PDF conversion and form utility based on pdftk

YiiRedisPHP 131

A set of wrappers for different data types in redis

yiipasswordPHP 81

Password strategies for Yii

yii2-dockerizedPHP 64

A template for docker based Yii 2 applications

YiiSolrPHP 50

A wrapper for the pecl solr library that provides common Yii constructs, such as models, data providers etc

php-shellcommandPHP 48

A simple object oriented interface to execute shell commands in PHP

Yii-Docs-GeneratorPHP 47

Generates HTML documentation for Yii applications

YiiGitPHP 36

A git wrapper for Yii, allows access to all git commands programatically

YiiElasticSearchPHP 32

Elastic Search client for Yii

YiiCurlPHP 30

A curl library for Yii

YiiStateMachinePHP 28

A state machine behavior for Yii

yii2-streamlogPHP 19

A Yii 2 log target for streams in URL format

oauth2yiiPHP 18

An OAuth2 client / server extension for the Yii framework

restyiiPHP 16

A RESTful extension for Yii.

packagecompressorPHP 16

A Javascript/CSS compressor based on Yii's package system

localeurlsPHP 12

Automatic locale/language management for URLs

php-excel-readerPHP 12

It reads the binary format of XLS files directly and can return values and formats from any cell. This project is the fork of http://code.google.com/p/php-excel-reader/ that, apparently, is no longer maintained.

pdfablePHP 10

A Yii extension to create PDFs with PHPWkHtmlToPdf/wkhtmltopdf

yii-api-vimPHP 8

Yii API manual plugin for VIM

yii2-excel-messagePHP 7

Translate messages via Excel files

yii2-bs3activeformPHP 7

A Bootstrap 3 enhanced ActiveForm for Yii 2

xcrudcontrollerPHP 7

A base class to quickly build customized CRUD interfaces.

handlebarsphpPHP 6

Transpiles handlebars templates into native PHP templates

Yii-Package-ManagerPHP 6

A package manager for Yii

php-tmpfilePHP 6

A convenience class for temporary files

yii2-apidoc-vimPHP 5

Yii2 apidoc as Vim helpfiles

php-orientdbPHP 5

A fast PHP driver for the OrientDB binary protocol.

YiiUsersPHP 4

User management for Yii

translatablePHP 4

Transparent attribute translation for ActiveRecords

flushablePHP 3

Yii dependency that allows to flush records from the cache

Yii-Resource-ManagerPHP 3

Helpers to allow Yii to interact with resources (files) of different types

bs3activeformPHP 2

A lightweight utility to render Bootstrap 3 forms in Yii

YiiEmailerPHP 2

Emailing functions for Yii

AccessRestrictablePHP 2

A Yii ActiveRecordBehavior that automatically applies conditions for access restriction to every query.

defaultpersisterPHP 1

Yii extension to save and restore model values in user session.

hybridauthmanagerPHP 1

An AuthManager for Yii that stores the hierarchy in a flat PHP file and the assignments in DB

YiiLinkablePHP 1

A simple extension for Yii allowing easy and consistent access to model URLs and appropriate anchor text.

YiiYaaPHP 1

YAA is an additional abstraction layer for Yii that aggregates a number of child models into a clean single model that is easy to cache


Yii extension to create URLs that allow to return to a page by storing its GET Parameters on a stack.


Work with PHP files in Active Record way


An alternative Yii2 application template for purists


simple useless twitter client