Yii 1.1: How to customize Yii core messages?

19 followers

Yii core messages refer to static text strings in the core Yii framework code which are meant to be displayed to end-users (e.g. core exception messages, default validation error messages). Customization of these core messages is needed in two circumstances:

  • When an application is written for non-English users, these core messages need to be translated and the framework does not have the required translation.
  • Some core messages need to be modified slightly for various reasons. For example, the messages are too technical; the messages are inappropriate in certain scenarios; the messages contain syntax errors. In the last example, bugs should be reported, but not every application can wait till the bugs are fixed.

In this article, we introduce a technique to customize the core messages in a systematic way. If you are only interested in customizing a few validation error messages, you may refer to the article "How to customize the error message of a validation rule".

When Yii displays a core message, it actually undergoes an implicit translation process with the help of an application component named "coreMessages". The component translates the core message into the target language which is displayed ultimately. If a translation cannot be found, the original core message will be displayed, instead.

The idea here is to customize the coreMessages component by changing the place where it looks for translated messages. We can do so by configuring the component with the following application configuration:

return array(
    ......
    'language'=>'de',
    'components'=>array(
        'coreMessages'=>array(
            'basePath'=>null,
        ),
        ......
    ),
);

In the above, we specify that the application is targeted to German users and that the translated messages are to be loaded from under the default basePath of the coreMessages component, which by default is the directory represented by the path alias application.messages. The latter effectively translates to the protected/messages folder, regardless of where protected is located in the filesystem. Please refer to the Yii Guide for more information about path aliases.

It might seem odd that we set the basePath to null instead of protected/messages. The reason we do that is to support the case where the protected folder has been moved out of the webroot, because the relative path protected/messages will then not be found starting from the webroot. The webroot is where the Yii application is located in the filesystem during runtime.

If we want to specify another basePath for the messages than this default one, we have to provide either an absolute path to the folder (such as /var/www/messages), or a path that during runtime will be relative the webroot (for example ../protected/messages if the protected directory is a located in the same directory as the webroot, i.e. moved one step up from the default location).

Next, we need to provide our translations. Under the directory protected/messages, create a subdirectory named de which corresponds to the target language we set in the application configuration. And under the de directory, create a new file named yii.php. To this end, we should have the following directory structure:

WebRoot/
    protected/
        messages/
            de/
                yii.php
        controllers/
        views/
        ......

Finally, we put message translations in the yii.php file. To save time, we may simply copy the content from framework/messages/de/yii.php and modify it as needed.

Tip: You may wonder why we would take so much trouble in order to customize the core messages. Why don't we modify the file framework/messages/de/yii.php directly? The answer is that you should never modify any core framework file. If you do that, you will face the danger that a future upgrade of the framework may overwrite your change.

Total 7 comments

#14463 report it
dannythebestguy at 2013/08/13 01:05pm
Not able to set the Base path

I tried the above process. Whatever path I give it takes the default path/messages only.

#11838 report it
audichya at 2013/02/07 01:11am
using messages instead of coreMessages and setting basePath using alias

andredelorme you can set messages component as follows :

return array(
    ......
    'language'=>'de',
    'components'=>array(
        'messages'=>array(
            'basePath'=>Yiibase::getPathOfAlias('application.messages')
        ),
        ......
    ),
);

Here basePath of message is set using ALIAS.

#9479 report it
jcsmesquita at 2012/08/15 01:20am
Bug?

Hi Qiang, first of all thanks for this post! I've followed your instructions and managed to get my CGridView zii translations read from protected/messages/zh_tw/zii.php

The problem is now all the other translations aren't working, it seems that the application isn't falling back to the core messages in Yii/framework/messages when it can't find one in protected/messages.

Am I missing something? Is there a bug in this feature?

I've tried it with Yii versions 1.1.10 and 1.1.11 but no cigar.

Has anyone been able to get the fallback working?

Cheers, jc

#4899 report it
rAWTAZ at 2011/08/26 08:20am
Updated to work even if you changed the location of the protected folder

The previous instructions only worked if the protected folder was in the default location, i.e. in the webroot. I've changed the basePath setting to one that works in case you moved the protected folder, and added elaborate information about other ways to define this as well.

#4013 report it
andredelorme at 2011/05/27 10:02am
Current OK?

This solution is still possible? I tried to redefine de basePath, but I get this error:

Property "CWebApplication.coreMessages" is read only.

#13 report it
Not Entered at 2010/10/12 08:45am
Some solution

Hi, today I also try to do the same. The problem exists. After some search in the source it seems that Yii is expecting to have full path for the 'baseName', so I make this:

'basePath'=>dirname(FILE).DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.'messages'

And it is now working :)

#1569 report it
sluderitz at 2009/06/21 05:10pm
Only customize some messages

Instead of copying the whole yii.php file you could use the initial one like this:

<?php return CMap::mergeArray( require(Yii::getFrameworkPath().'/messages/de/yii.php'), array( 'Page:' => 'Seite:', ... ) );

This has the advantage that when new messages are added to the original yii.php file you will not have to change the custom yii.php file

Leave a comment

Please to leave your comment.

Write new article