Yii 1.1: langhandler

Creates and parses languages codes in url (i18n)

This extension will set up your applications target language according to visitors browser setting, accepted languages list and country code passed in url.


Change Log

June 11, 2013

  • Updated to 1.2 REMOVED (Dead end) Actually improvements in langhandler are not needed. Currently language detection suffers from 2429 bug, which is particularly burdensome in Android browser.

    -Improved language detection in non strict mode.

October 18, 2011

  • Updated to 1.1
    -read update section above for details.

July 17, 2009

  • Bugfix #1
    -small typo fixed Thx to cosimfi74

July 12, 2009

  • Initial release.


Update to 1.1 (18.10.2011)

After a long time langhandler has been updated to version 1.1 (version of langhandler, not Yii). There is an optional boolean parameter $strict available now. It defaults to false and can be set to true like any other component attribute:

'ELangHandler' => array (
            'class' => 'application.extensions.langhandler.ELangHandler',
            'languages' => array('pl','en','de'),
            'strict' => true,

If $strict is left to default false it will not try to compare browser's preferred language exactly like reported, instead it will try to extract language code only. When it is set to true langhandler functionality will not be changed compared to initial release.


  • prefered language (browser) => pl-PL; $strict=false; langhandler will use pl when searching languages array for supported codes.
  • prefered language (browser) => pl-PL; $strict=true; langhandler will use pl_PL when searching languages array for supported codes.

Notice that when language is reported with area code it will always be converted to canonical form with underscore separating codes. So if area matters for you (you may want to set locale based on area not only language) set $strict to true and insert codes pairs (ll_AA format) in languages array.


This update changes defaults compared to initial release, so if you are using ll_AA codes now remember to set $strict to true or your application may (and probably will) misbehave after updating to langhandler 1.1.


  • Yii 1.0 or above


  • Extract the release file under protected/extensions
  • add ELangHandler to preload array in main config file
  • add ELangHandler configuration in components array
'ELangHandler' => array (
            'class' => 'application.extensions.langhandler.ELangHandler',
            'languages' => array('pl','en','de'),

COMMENT: languages array should contain languages codes which will be accepted by application. sourceLanguage code doesn't have to be inserted, however it may be useful in some situations (will be explained later).

  • update urlManager configuration in components array
                '<lang:(pl|en|de)>/<_c>/<_a>/' => '<_c>/<_a>',  

COMMENT: urlFormat and showScriptName aren't required but recommended. Route rule and class override are a required minimum.


After component has been configured like in examples above, application will support 3 target languages Polish (pl), English (en), German (de) and source language (yii defaults to en_us). Once language has been chosen langhandler will make sure that its code is passed in url in every request. If language is not specified in url, langhandler will try to recognize browser preffered language and use it, if its code is present in languages array in configuration file. If browser prefered language is not supported by your app, first language from configuration array will be used.


source language (en) supported languages (de,pl)

  • prefered language (browser) => pl; application lang => pl because pl is in supported languages array
  • prefered language (browser) => en; application lang => en because source language is always a supported language
  • prefered language (browser) => jp; application lang => de because japanese language is not supported and first language from supported languages array is used. Thats why sometimes its worth to add sourceLanguage to langhandlers languages array.

When adding or removing supported languages remember to alter route rules as well.

If you want to change language simply add lang variable with language code to url.


<?php echo CHtml::link('this link will open current page in german',array('','lang'=>'de')) ?>

For more information about translating core messages, views and other files check Yii documentation

Total 12 comments

#11269 report it
Patrick H at 2013/01/02 02:13pm
domain.com -> domain.com/lang rule needed

Here is my config/main.php for clean URLs with lang code

'urlManager' => array(
            'class' => 'ext.langhandler.ELangCUrlManager',
            'urlFormat' => 'path',
            'showScriptName' => false,
            'caseSensitive' => false,
            'rules' => array(
                '<lang:\w+>' => 'site/index',
                '<lang:\w+>/<action:\w+>' => 'site/<action>',

Now I want that if a user calls domain.com the url should be rewritten to domain.com/en How is that possible? Thanks.

#10047 report it
bobafett at 2012/10/01 11:22pm
Preload not working

Thanks for the extension..

The preload of the ELangHandler is not working. Only the log preload.

'preload' => array('log', 'ELangHandler'),

Any idea why is being skipped? I'm using the yii-environment extension, but I don't know if its has something to do because the log components is being preload.

Thank you.

#9715 report it
Cobra at 2012/09/05 08:14am
it works!

Awesome extension, works like a charm.

#5521 report it
sidewinder at 2011/10/18 04:30am
Thanks for downloading

I've been away for a while and I was really surprised when I saw how popular this extension has become. Thank you all for comments and downloads :).

#407 report it
mech7 at 2010/06/11 03:30am

thx for sharing i needed to change the route though to make it work with parameters ;)

'<lang:(th|en|de)>/<_c>/<_a>/*' => '<_c>/<_a>/',

#422 report it
choiceerp at 2010/06/07 05:59am
That was exactly what I needed.

Work perfect

#993 report it
schmunk at 2010/01/13 10:37am

That was exactly what I needed.

If you're working with modules, you may also add this rule:

'<lang:[a-z]{2}_[a-z]{2,}>/<_m>/<_c>/<_a>' => '<_m>/<_c>/<_a>',

#1151 report it
jerry2801 at 2009/11/21 10:06pm
same to Yurik


will build: http://abc.com/lang/zh_cn/

if (!isset($params['lang']))

modify to

if (!isset($params['lang']) && Yii::app()->GetLanguage()!=Yii::app()->components['ELangHandler']->languages[0])

is work! and build: http://abc.com/

#1430 report it
sidewinder at 2009/08/04 05:51am
Please ask questions on forums

Please ask questions on this forums thread. This is for reviews only.

Yes its free for commercial use as long as you keep license copy with your software. Please check license tab on top of the screen for details.

#1433 report it
jackiesun at 2009/08/03 11:08pm
is this free for business ?

is this free for business ?

#1466 report it
Yurik at 2009/07/27 03:40pm
No changes in URLs if site language is default

Forward thanks a lot 4 your extension!

I think, if current site language is default (equals site language in config) there's no need to modify URLs by adding language in URLs.

To use this method I changed a little ELangCUrlManager.php in line 6 from:

if (!isset($params['lang']))


if (!isset($params['lang']) && Yii::app()->GetLanguage()!=Yii::app()->components['ELangHandler']->languages[0])
#1492 report it
cosimfi74 at 2009/07/17 08:59am
little bug

is work.

but a little bug the name of the file ELangCUrlManager.php rename in ElangCUrlManager.php

Is possible to use urlformat='get'...

Leave a comment

Please to leave your comment.

Create extension