langhandler Follow @yiiframework

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

Resources ¶

• Join discussion

Documentation ¶

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.

EXAMPLE

• 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.

WARNING

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.

Requirements ¶

• Yii 1.0 or above

Installation ¶

• Extract the release file under protected/extensions
• add ELangHandler to preload array in main config file

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

• 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

'urlManager'=>array(
            'class'=>'application.extensions.langhandler.ELangCUrlManager',
            'urlFormat'=>'path',
            'showScriptName'=>false,
            'rules'=>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.

Usage ¶

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.

EXAMPLE

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 japan 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.

EXAMPLE

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

Change Log ¶

July 12, 2009 ¶

• Initial release.

July 17, 2009 ¶

• Bugfix #1
  -small typo fixed Thx to cosimfi74

October 18, 2011 ¶

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