Yii2 yii php messages
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|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:
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.
Class yii\i18n\PhpMessageSource
PhpMessageSource uses PHP arrays to keep message translations.
- Each PHP script contains one array which stores the message translations in one particular language and for a single message category;
- Each PHP script is saved as a file named as «$basePath/LanguageID/CategoryName.php»;
- Within each PHP script, the message translations are returned as an array like the following:
return [ 'original message 1' => 'translated message 1', 'original message 2' => 'translated message 2', ]; You may use $fileMap to customize the association between category names and the file names.
Public Properties
| Property | Type | Description | Defined By |
|---|---|---|---|
| $basePath | string | The base path for all translated messages. | yii\i18n\PhpMessageSource |
| $behaviors | yii\base\Behavior[] | List of behaviors attached to this component. | yii\base\Component |
| $fileMap | array | Mapping between message categories and the corresponding message file paths. | yii\i18n\PhpMessageSource |
| $forceTranslation | boolean | Whether to force message translation when the source and target languages are the same. | yii\i18n\MessageSource |
| $sourceLanguage | string|null | The language that the original messages are in. | yii\i18n\MessageSource |
Public Methods
| Method | Description | Defined By |
|---|---|---|
| __call() | Calls the named method which is not a class method. | yii\base\Component |
| __clone() | This method is called after the object is created by cloning an existing one. | yii\base\Component |
| __construct() | Constructor. | yii\base\BaseObject |
| __get() | Returns the value of a component property. | yii\base\Component |
| __isset() | Checks if a property is set, i.e. defined and not null. | yii\base\Component |
| __set() | Sets the value of a component property. | yii\base\Component |
| __unset() | Sets a component property to be null. | yii\base\Component |
| attachBehavior() | Attaches a behavior to this component. | yii\base\Component |
| attachBehaviors() | Attaches a list of behaviors to the component. | yii\base\Component |
| behaviors() | Returns a list of behaviors that this component should behave as. | yii\base\Component |
| canGetProperty() | Returns a value indicating whether a property can be read. | yii\base\Component |
| canSetProperty() | Returns a value indicating whether a property can be set. | yii\base\Component |
| className() | Returns the fully qualified name of this class. | yii\base\BaseObject |
| detachBehavior() | Detaches a behavior from the component. | yii\base\Component |
| detachBehaviors() | Detaches all behaviors from the component. | yii\base\Component |
| ensureBehaviors() | Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component |
| getBehavior() | Returns the named behavior object. | yii\base\Component |
| getBehaviors() | Returns all behaviors attached to this component. | yii\base\Component |
| hasEventHandlers() | Returns a value indicating whether there is any handler attached to the named event. | yii\base\Component |
| hasMethod() | Returns a value indicating whether a method is defined. | yii\base\Component |
| hasProperty() | Returns a value indicating whether a property is defined for this component. | yii\base\Component |
| init() | Initializes this component. | yii\i18n\MessageSource |
| off() | Detaches an existing event handler from this component. | yii\base\Component |
| on() | Attaches an event handler to an event. | yii\base\Component |
| translate() | Translates a message to the specified language. | yii\i18n\MessageSource |
| trigger() | Triggers an event. | yii\base\Component |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| getMessageFilePath() | Returns message file path for the specified language and category. | yii\i18n\PhpMessageSource |
| loadFallbackMessages() | The method is normally called by loadMessages() to load the fallback messages for the language. | yii\i18n\PhpMessageSource |
| loadMessages() | Loads the message translation for the specified $language and $category. | yii\i18n\PhpMessageSource |
| loadMessagesFromFile() | Loads the message translation for the specified language and category or returns null if file doesn’t exist. | yii\i18n\PhpMessageSource |
| translateMessage() | Translates the specified message. | yii\i18n\MessageSource |
Events
| Event | Type | Description | Defined By |
|---|---|---|---|
| EVENT_MISSING_TRANSLATION | yii\i18n\MissingTranslationEvent | An event that is triggered when a message translation is not found. | yii\i18n\MessageSource |