langhandler Creates and parses languages codes in url (i18n)

  1. Change Log
  2. Documentation

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 llAA 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

21 0
2 203 downloads
Yii Version: 1.1
License: BSD-2-Clause
Category: Others
Developed by: sidewinder
Created on: Jul 12, 2009
Last updated: 10 years ago


show all

Related Extensions