<commit_before>Internationalization
====================

Internationalization (I18N) refers to the process of designing a software
application so that it can be adapted to various languages and regions
without engineering changes. For Web applications, this is of particular
importance because the potential users may be from worldwide.

Yii provides support for I18N in several aspects.

   - It provides the locale data for each possible language and variant.
   - It provides message and file translation service.
   - It provides locale-dependent date and time formatting.
   - It provides locale-dependent number formatting.

In the following subsections, we will elaborate each of the above aspects.

Locale and Language
-------------------

Locale is a set of parameters that defines the user's language, country
and any special variant preferences that the user wants to see in their
user interface. It is usually identified by an ID consisting of a language
ID and a region ID. For example, the ID `en_US` stands for the locale of
English and United States. For consistency, all locale IDs in Yii are
canonicalized to the format of `LanguageID` or `LanguageID_RegionID`
in lower case (e.g. `en`, `en_us`).

Locale data is represented as a [CLocale] instance. It provides
locale-dependent information, including currency symbols, number symbols,
currency formats, number formats, date and time formats, and date-related
names. Since the language information is already implied in the locale ID,
it is not provided by [CLocale]. For the same reason, we often
interchangeably using the term locale and language.

Given a locale ID, one can get the corresponding [CLocale] instance by
`CLocale::getInstance($localeID)` or `CApplication::getLocale($localeID)`.

> Info: Yii comes with locale data for nearly every language and region.
The data is obtained from [Common Locale Data Repository](http://unicode.org/cldr/) (CLDR). For each locale, only a
subset of the CLDR data is provided as the original data contains a lot of
rarely used information. Starting from version 1.1.0, users can also supply
their own customized locale data. To do so, configure the [CApplication::localeDataPath]
property with the directory that contains the customized locale data.
Please refer to the locale data files under `framework/i18n/data` in order
to create customized locale data files.

For a Yii application, we differentiate its [target
language|CApplication::language] from [source
language|CApplication::sourceLanguage]. The target language is the language
(locale) of the users that the application is targeted at, while the source
language refers to the language (locale) that the application source files
are written in. Internationalization occurs only when the two languages are
different.

One can configure [target language|CApplication::language] in the
[application configuration](/doc/guide/basics.application#application-configuration), or
change it dynamically before any internationalization occurs.

> Tip: Sometimes, we may want to set the target language as the language
preferred by a user (specified in user's browser preference). To do so, we
can retrieve the user preferred language ID using
[CHttpRequest::preferredLanguage].

Translation
-----------

The most needed I18N feature is perhaps translation, including message
translation and view translation. The former translates a text message to
the desired language, while the latter translates a whole file to the
desired language.

A translation request consists of the object to be translated, the source
language that the object is in, and the target language that the object
needs to be translated to. In Yii, the source language is default to the
[application source language|CApplication::sourceLanguage] while the target
language is default to the [application language|CApplication::language].
If the source and target languages are the same, translation will not
occur.

### Message Translation

Message translation is done by calling [Yii::t()|YiiBase::t]. The method
translates the given message from [source
language|CApplication::sourceLanguage] to [target
language|CApplication::language].

When translating a message, its category has to be specified since a
message may be translated differently under different categories
(contexts). The category `yii` is reserved for messages used by the Yii
framework core code.

Messages can contain parameter placeholders which will be replaced with
the actual parameter values when calling [Yii::t()|YiiBase::t]. For
example, the following message translation request would replace the
`{alias}` placeholder in the original message with the actual alias value.

~~~
[php]
Yii::t('app', 'Path alias "{alias}" is redefined.',
	array('{alias}'=>$alias))
~~~

> Note: Messages to be translated must be constant strings. They should
not contain variables that would change message content (e.g. `"Invalid
{$message} content."`). Use parameter placeholders if a message needs to
vary according to some parameters.

Translated messages are stored in a repository called *message
source*. A message source is represented as an instance of
[CMessageSource] or its child class. When [Yii::t()|YiiBase::t] is invoked,
it will look for the message in the message source and return its
translated version if it is found.

Yii comes with the following types of message sources. You may also extend
[CMessageSource] to create your own message source type.

   - [CPhpMessageSource]: the message translations are stored as key-value
pairs in a PHP array. The original message is the key and the translated
message is the value. Each array represents the translations for a
particular category of messages and is stored in a separate PHP script file
whose name is the category name. The PHP translation files for the same
language are stored under the same directory named as the locale ID. And
all these directories are located under the directory specified by
[basePath|CPhpMessageSource::basePath].

   - [CGettextMessageSource]: the message translations are stored as [GNU
Gettext](http://www.gnu.org/software/gettext/) files.

   - [CDbMessageSource]: the message translations are stored in database
tables. For more details, see the API documentation for [CDbMessageSource].

A message source is loaded as an [application
component](/doc/guide/basics.application#application-component). Yii pre-declares an
application component named [messages|CApplication::messages] to store
messages that are used in user application. By default, the type of this
message source is [CPhpMessageSource] and the base path for storing the PHP
translation files is `protected/messages`.

In summary, in order to use message translation, the following steps are
needed:

   1. Call [Yii::t()|YiiBase::t] at appropriate places;

   2. Create PHP translation files as
`protected/messages/LocaleID/CategoryName.php`. Each file simply returns an
array of message translations. Note, this assumes you are using the default
[CPhpMessageSource] to store the translated messages.

   3. Configure [CApplication::sourceLanguage] and [CApplication::language].

> Tip: The `yiic` tool in Yii can be used to manage message translations
when [CPhpMessageSource] is used as the message source. Its `message` command
can automatically extract messages to be translated from selected source files
and merge them with existing translations if necessary.

Starting from version 1.0.10, when using [CPhpMessageSource] to manage message source,
messages for an extension class (e.g. a widget, a module) can be specially managed and used. In particular, if a message
belongs to an extension whose class name is `Xyz`, then the message category can be specified
in the format of `Xyz.categoryName`. The corresponding message file will be assumed to be
`BasePath/messages/LanguageID/categoryName.php`, where `BasePath` refers to
the directory that contains the extension class file. And when using `Yii::t()` to
translate an extension message, the following format should be used, instead:
<commit_msg>Added yiic help message to i18n guide<commit_after>Internationalization
====================

Internationalization (I18N) refers to the process of designing a software
application so that it can be adapted to various languages and regions
without engineering changes. For Web applications, this is of particular
importance because the potential users may be from worldwide.

Yii provides support for I18N in several aspects.

   - It provides the locale data for each possible language and variant.
   - It provides message and file translation service.
   - It provides locale-dependent date and time formatting.
   - It provides locale-dependent number formatting.

In the following subsections, we will elaborate each of the above aspects.

Locale and Language
-------------------

Locale is a set of parameters that defines the user's language, country
and any special variant preferences that the user wants to see in their
user interface. It is usually identified by an ID consisting of a language
ID and a region ID. For example, the ID `en_US` stands for the locale of
English and United States. For consistency, all locale IDs in Yii are
canonicalized to the format of `LanguageID` or `LanguageID_RegionID`
in lower case (e.g. `en`, `en_us`).

Locale data is represented as a [CLocale] instance. It provides
locale-dependent information, including currency symbols, number symbols,
currency formats, number formats, date and time formats, and date-related
names. Since the language information is already implied in the locale ID,
it is not provided by [CLocale]. For the same reason, we often
interchangeably using the term locale and language.

Given a locale ID, one can get the corresponding [CLocale] instance by
`CLocale::getInstance($localeID)` or `CApplication::getLocale($localeID)`.

> Info: Yii comes with locale data for nearly every language and region.
The data is obtained from [Common Locale Data Repository](http://unicode.org/cldr/) (CLDR). For each locale, only a
subset of the CLDR data is provided as the original data contains a lot of
rarely used information. Starting from version 1.1.0, users can also supply
their own customized locale data. To do so, configure the [CApplication::localeDataPath]
property with the directory that contains the customized locale data.
Please refer to the locale data files under `framework/i18n/data` in order
to create customized locale data files.

For a Yii application, we differentiate its [target
language|CApplication::language] from [source
language|CApplication::sourceLanguage]. The target language is the language
(locale) of the users that the application is targeted at, while the source
language refers to the language (locale) that the application source files
are written in. Internationalization occurs only when the two languages are
different.

One can configure [target language|CApplication::language] in the
[application configuration](/doc/guide/basics.application#application-configuration), or
change it dynamically before any internationalization occurs.

> Tip: Sometimes, we may want to set the target language as the language
preferred by a user (specified in user's browser preference). To do so, we
can retrieve the user preferred language ID using
[CHttpRequest::preferredLanguage].

Translation
-----------

The most needed I18N feature is perhaps translation, including message
translation and view translation. The former translates a text message to
the desired language, while the latter translates a whole file to the
desired language.

A translation request consists of the object to be translated, the source
language that the object is in, and the target language that the object
needs to be translated to. In Yii, the source language is default to the
[application source language|CApplication::sourceLanguage] while the target
language is default to the [application language|CApplication::language].
If the source and target languages are the same, translation will not
occur.

### Message Translation

Message translation is done by calling [Yii::t()|YiiBase::t]. The method
translates the given message from [source
language|CApplication::sourceLanguage] to [target
language|CApplication::language].

When translating a message, its category has to be specified since a
message may be translated differently under different categories
(contexts). The category `yii` is reserved for messages used by the Yii
framework core code.

Messages can contain parameter placeholders which will be replaced with
the actual parameter values when calling [Yii::t()|YiiBase::t]. For
example, the following message translation request would replace the
`{alias}` placeholder in the original message with the actual alias value.

~~~
[php]
Yii::t('app', 'Path alias "{alias}" is redefined.',
	array('{alias}'=>$alias))
~~~

> Note: Messages to be translated must be constant strings. They should
not contain variables that would change message content (e.g. `"Invalid
{$message} content."`). Use parameter placeholders if a message needs to
vary according to some parameters.

Translated messages are stored in a repository called *message
source*. A message source is represented as an instance of
[CMessageSource] or its child class. When [Yii::t()|YiiBase::t] is invoked,
it will look for the message in the message source and return its
translated version if it is found.

Yii comes with the following types of message sources. You may also extend
[CMessageSource] to create your own message source type.

   - [CPhpMessageSource]: the message translations are stored as key-value
pairs in a PHP array. The original message is the key and the translated
message is the value. Each array represents the translations for a
particular category of messages and is stored in a separate PHP script file
whose name is the category name. The PHP translation files for the same
language are stored under the same directory named as the locale ID. And
all these directories are located under the directory specified by
[basePath|CPhpMessageSource::basePath].

   - [CGettextMessageSource]: the message translations are stored as [GNU
Gettext](http://www.gnu.org/software/gettext/) files.

   - [CDbMessageSource]: the message translations are stored in database
tables. For more details, see the API documentation for [CDbMessageSource].

A message source is loaded as an [application
component](/doc/guide/basics.application#application-component). Yii pre-declares an
application component named [messages|CApplication::messages] to store
messages that are used in user application. By default, the type of this
message source is [CPhpMessageSource] and the base path for storing the PHP
translation files is `protected/messages`.

In summary, in order to use message translation, the following steps are
needed:

   1. Call [Yii::t()|YiiBase::t] at appropriate places;

   2. Create PHP translation files as
`protected/messages/LocaleID/CategoryName.php`. Each file simply returns an
array of message translations. Note, this assumes you are using the default
[CPhpMessageSource] to store the translated messages.

   3. Configure [CApplication::sourceLanguage] and [CApplication::language].

> Tip: The `yiic` tool in Yii can be used to manage message translations
when [CPhpMessageSource] is used as the message source. Its `message` command
can automatically extract messages to be translated from selected source files
and merge them with existing translations if necessary. For more details of using
the `message` command, please run `yiic help message`.

Starting from version 1.0.10, when using [CPhpMessageSource] to manage message source,
messages for an extension class (e.g. a widget, a module) can be specially managed and used. In particular, if a message
belongs to an extension whose class name is `Xyz`, then the message category can be specified
in the format of `Xyz.categoryName`. The corresponding message file will be assumed to be
`BasePath/messages/LanguageID/categoryName.php`, where `BasePath` refers to
the directory that contains the extension class file. And when using `Yii::t()` to
translate an extension message, the following format should be used, instead:

{'fraction_non_alphanumeric': 0.062104162823587286, 'fraction_numerical': 0.0023365922646498187, 'mean_word_length': 5.030404152762329, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '892922', 'n_tokens_mistral': 3919, 'n_tokens_neox': 3794, 'n_words': 2213}