> Note that formatting may differ between different versions of the ICU library compiled with PHP and also based on the fact whether the
> [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed or not. So to ensure your website works with the same output
> in all environments it is recommended to install the PHP intl extension in all environments and verify that the version of the ICU library
> is the same.
> is the same. See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
Configuring the format
----------------------
The default format of the Formatter class can be adjusted using the properties of the formatter class.
You can adjust these values application wide by configuring the `formatter` component in your [application config](concept-configurations.md#application-configurations)
an example configuration is shown in the following.
For more details about certain properties check out the [[yii\i18n\Formatter|API documentation of the Formatter class]].
You can adjust these values application wide by configuring the `formatter` component in your [application config](concept-configurations.md#application-configurations).
An example configuration is shown in the following.
For more details about the available properties check out the [[yii\i18n\Formatter|API documentation of the Formatter class]].
```php
'components' => [
...
...
@@ -74,6 +74,8 @@ For more details about certain properties check out the [[yii\i18n\Formatter|API
Formatting Dates
----------------
> Note: This section is under development.
TDB
See http://site.icu-project.org/ for the format.
...
...
@@ -89,6 +91,8 @@ See http://site.icu-project.org/ for the format.
Formatting Numbers
------------------
> Note: This section is under development.
TDB
See http://site.icu-project.org/ for the format.
...
...
@@ -105,6 +109,8 @@ See http://site.icu-project.org/ for the format.
In order to use advanced features you need to install and enable [intl](http://www.php.net/manual/en/intro.intl.php) PHP
extension. After installing and enabling it you will be able to use extended syntax for placeholders. Either short form
In order to use advanced features you need to install and enable the [intl PHP extension](http://www.php.net/manual/en/intro.intl.php).
After installing and enabling it you will be able to use extended syntax for placeholders. Either short form
`{placeholderName, argumentType}` that means default setting or full form `{placeholderName, argumentType, argumentStyle}`
that allows you to specify formatting style.
Full reference is [available at ICU website](http://icu-project.org/apiref/icu4c/classMessageFormat.html) but since it's
a bit cryptic we have our own reference below.
A complete reference is available at the [ICU website](http://icu-project.org/apiref/icu4c/classMessageFormat.html) but we will show some examples in the following.
Built in formats (`short`, `medium`, `long`, `full`):
Built in formats are `short`, `medium`, `long`, and `full`:
```php
echo\Yii::t('app','It is {0, time, short}',time());
```
Custom pattern:
You may also specify a custom pattern:
```php
echo\Yii::t('app','It is {0, date, HH:mm}',time());
...
...
@@ -218,7 +225,6 @@ Will produce "You are 42nd visitor here!".
#### Duration
```php
echo\Yii::t('app','You are here for {n, duration} already!',['n'=>47]);
```
...
...
@@ -229,7 +235,7 @@ Will produce "You are here for 47 sec. already!".
Different languages have different ways to inflect plurals. Some rules are very complex so it's very handy that this
functionality is provided without the need to specify inflection rule. Instead it only requires your input of inflected
word in certain situations.
words in certain situations.
```php
echo\Yii::t('app','There {n, plural, =0{are no cats} =1{is one cat} other{are # cats}}!',['n'=>0]);
...
...
@@ -247,14 +253,14 @@ for Russian:
In the above it worth mentioning that `=1` matches exactly `n = 1` while `one` matches `21` or `101`.
Note that if you are using placeholder twice and one time it's used as plural another one should be used as number else
Note that if you are using a placeholder twice and one time it's used as `plural` another one should be used as `number` else
you'll get "Inconsistent types declared for an argument: U_ARGUMENT_TYPE_MISMATCH" error:
```
Total {count, number} {count, plural, one{item} other{items}}.
```
To learn which inflection forms you should specify for your language you can referrer to
To learn which inflection forms you should specify for your language you can referrer to the
[rules reference at unicode.org](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html).
#### Selections
...
...
@@ -271,13 +277,13 @@ echo \Yii::t('app', '{name} is {gender} and {gender, select, female{she} male{he
Will produce "Snoopy is dog and it loves Yii!".
In the expression `female` and `male` are possible values. `other` handler values that do not match. Strings inside
In the expression `female` and `male` are possible values. `other` handles values that do not match. Strings inside
brackets are sub-expressions so could be just a string or a string with more placeholders.
### Specifying default translation
You can specify default translation that will be used as a fallback for categories that don't match any other translation.
This translation should be marked with `*`. In order to do it add the following to the config file (for the `yii2-basic` application it will be `web.php`):
You can specify default translations that will be used as a fallback for categories that don't match any other translation.
This translation should be marked with `*`. In order to do it add the following to the application config:
```php
//configure i18n component
...
...
@@ -291,8 +297,8 @@ This translation should be marked with `*`. In order to do it add the following
],
```
Now you can use categories without configuring each one that is similar to Yii 1.1 behavior.
Messages for the category will be loaded from a file under default translation `basePath` that is `@app/messages`:
Now you can use categories without configuring each one, which is similar to Yii 1.1 behavior.
Messages for the category will be loaded from a file under the default translation `basePath` that is `@app/messages`:
```php
echoYii::t('not_specified_category','message from unspecified category');
...
...
@@ -302,7 +308,7 @@ Message will be loaded from `@app/messages/<LanguageCode>/not_specified_category
### Translating module messages
If you want to translate messages for a module and avoid using a single translation file for all messages, you can make it like the following:
If you want to translate messages for a module and avoid using a single translation file for all messages, you can do it like the following:
```php
<?php
...
...
@@ -348,7 +354,7 @@ use convention of category mapping to the same named file and use `Module::t('va
### Translating widgets messages
Same rules can be applied for widgets too, for example:
The same rule as applied for Modules above can be applied for widgets too, for example:
```php
<?php
...
...
@@ -400,34 +406,33 @@ Instead of using `fileMap` you can simply use convention of category mapping to
### Translating framework messages
Sometimes you want to correct default framework message translation for your application. In order to do so configure
`i18n` component like the following:
Yii comes with default translation messages for validation errors and some other strings. These messages are all
in the category `yii`. Sometimes you want to correct default framework message translation for your application.
In order to do so configure the `i18n`[application component](concept-components.md) like the following:
```php
'components'=>[
'i18n'=>[
'translations'=>[
'yii'=>[
'class'=>'yii\i18n\PhpMessageSource',
'sourceLanguage'=>'en-US',
'basePath'=>'/path/to/my/message/files'
],
'i18n'=>[
'translations'=>[
'yii'=>[
'class'=>'yii\i18n\PhpMessageSource',
'sourceLanguage'=>'en-US',
'basePath'=>'@app/messages'
],
],
],
```
Now you can place your adjusted translations to `/path/to/my/message/files`.
Now you can place your adjusted translations to `@app/messages/<language>/yii.php`.
### Handling missing translations
If the translation is missing at the source, Yii displays the requested message content. Such behavior very convenient
If the translation is missing at the source, Yii displays the requested message content. Such behavior is very convenient
in case your raw message is a valid verbose text. However, sometimes it is not enough.
You may need to perform some custom processing of the situation, when requested translation is missing at the source.
This can be achieved via 'missingTranslation' event of the[[yii\i18n\MessageSource]].
This can be achieved using the [[yii\i18n\MessageSource::EVENT_MISSING_TRANSLATION|missingTranslation]]-event of[[yii\i18n\MessageSource]].
For example: lets mark all missing translations with something notable, so they can be easily found at the page.
First we need to setup event handler, this can be done via configuration:
For example to mark all missing translations with something notable, so they can be easily found at the page we
first we need to setup event handler. This can be done in the application configuration:
```php
'components'=>[
...
...
@@ -440,16 +445,20 @@ First we need to setup event handler, this can be done via configuration:
