Difference between #6 and #5 of How to customize Yii core messages?

unchanged
Title
How to customize Yii core messages?
unchanged
Category
Tutorials
unchanged
Tags
core messages, translation, i18n
changed
Content
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](/doc/cookbook/1/)".

When Yii displays a core message, it actually undergoes an implicit translation
process with the help of an application component named
"[coreMessages|CApplication::coreMessages]". The component translates
the core message into the [target language|CApplication::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:

~~~
[php]
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](doc/guide/basics.namespace).

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.

### Links
[Chinese version](http://projects.ourplanet.tk/node/105)