A custom URL rule class for Yii 2 which allows to create translated URL rules

Installs: 7 459

Dependents: 0

Suggesters: 0

Security: 0

Stars: 10

Watchers: 4

Forks: 7

Open Issues: 0


v1.2.1 2018-09-26 22:16 UTC

This package is auto-updated.

Last update: 2021-11-11 22:50:27 UTC


Latest Stable Version Total Downloads License

Yii2 TranslatableUrlRule

A custom URL rule class for Yii 2 which allows for translated URL rules.

This extension allows you to write URL rules per language. For example, you can have signup for en, aanmelden for nl and registrieren for de. Because this extension uses normal Yii2 UrlRule objects to build language-specific URL rules, you still have all power that comes with normal Yii URL rules, including URL parameters and regular expressions.

The current language is determined by the Yii::$app->language parameter. The value of this parameter is used to create and to parse URLs.

This extension does not set the current language parameter. Use codemix/yii2-localeurls for that.


The preferred way to install this extension is through composer.

Either run

composer require geertw/yii2-translatable-url-rule

or add

"geertw/yii2-translatable-url-rule": "*"

to the require section of your composer.json file.


Update your URL rules to use this class and set the patterns per language.

$rules = [
        'class' => 'geertw\Yii2\TranslatableUrlRule\TranslatableUrlRule',
        'patterns' => [
            'en' => '/signup',
            'nl' => '/aanmelden',
            'de' => '/registrieren',
        'route' => 'user/signup',
        'class' => 'geertw\Yii2\TranslatableUrlRule\TranslatableUrlRule',
        'patterns' => [
            'en' => '/user/<username>',
            'nl' => '/gebruiker/<username>',
            'de' => '/benutzer/<username>',
        'route' => 'user/view',

The route parameter remains the same for all rules. patterns is an array of all patterns, the key must equal the Yii language identifier. If there is no pattern for a language, the first configured pattern will be used.

Set forceRuleSearch to true to force searching in all rule patterns.

You may omit the class configuration in your URL rules when you configure a ruleConfig in UrlManager:

return [
    'components' => [
        'urlManager'   => [
            'ruleConfig' => [
                'class' => 'geertw\Yii2\TranslatableUrlRule\TranslatableUrlRule'
            'rules' => $rules,
            // Additional UrlManager configuration

Language switcher example

Due to the way this library works, you need to specify two language parameters when creating URLs for routes in another language.

The following two code snippets allow you to create a simple dropdown which allows users to select alternative languages for the current route:

Create a widget like this:


namespace frontend\components;

use Yii;
use yii\bootstrap\Dropdown;

class LanguageSwitcher extends Dropdown {
    public $langLabels;

    private $isError;

    public function init() {
        $route = Yii::$app->controller->route;
        $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 ($isWildcard) {
                $language = substr($language, 0, 2);
            $params['language'] = $language;
            $params['url-language'] = $language;
            $this->items[] = [
                'label' => $this->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 function label($code) {
        return isset($this->langLabels[$code]) ? $this->langLabels[$code] : null;

Insert the following code in your view code:

    <?= LanguageSwitcher::widget([
        'options'    => ['class' => 'pull-right'],
        'langLabels' => [
            'de' => 'German',
            'en' => 'English',
            'nl' => 'Nederlands',
    ]) ?>

You might recognize this example, as it is largely based on the example for yii2-localeurls.