# Development - Localization

### Internationalization ¶

Localization (sometimes shortened to "l10n") is the process of adapting a product or service to a particular language, culture, and desired local "look-and-feel." Ideally, a product or service is developed so that localization is relatively easy to achieve - for example, by creating technical illustrations for manuals in which the text can easily be changed to another language and allowing some expansion room for this purpose. This enabling process is termed internationalization. An internationalized product or service is therefore easier to localize. The process of first enabling a product to be localized and then localizing it for different national audiences is sometimes known as globalization. In localizing a product, in addition to idiomatic language translation, such details as time zones, money, national holidays, local color sensitivities, product or service names, gender roles, and geographic examples must all be considered. A successfully localized service or product is one that appears to have been developed within the local culture. Language translation, which is a large part of localization, can sometimes be facilitated with automatic language translation. However, much additional work is usually needed.

#### 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. This feature released in a basic frame for some languages in `framework/i18n/` directory. Users always may customize this feature to suit their needs.

#### Translation

This is the most needed feature of l10n and it including message translations. The former translates a text message 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 ApPHP Framework, the source language defaults to the application source language while the target language defaults to the application language.

### Localization ¶

#### Message Translation

Framework messages feature allow to implement the i10n (localization) concept. To release this feature the framework stores message files for each language in a special directory, called `messages`.
These files may be created for application and they contain the array of localizable messages and constants. You can modify them by translating the specific messages or create new files, specified for other category of messages. In these files each array element represents the translation (value) of a message (key). The default default name for application messages file is "app.php".
They must be:

- application/ application directory
  - messages/ directory where placed all message files
    - de directory where message for German language
      - app.php application translation in German
      - news.php news module translation in German
    - en directory where message for English language
      - app.php application translation in English
      - news.php news module translation in English
    - es directory where message for Spanish language
      - app.php application translation in Spanish
      - news.php news module translation in Spanish
    ...

Below the example of such message file:

    return array (
        'Access' =>'Access',
        'Account Information' => 'Account Information',
        'Account Type' => 'Account Type',
        'Account Update Error Message' => 'An error occurred while updating the account! Please re-enter.',
        'Account Update Success Message' => 'Account {name} settings have been successfully updated.',
        'Accounts' => 'Accounts',
        'Actions' => 'Actions',
        'Active' => 'Active',
        ...
    );

Usage example:

    echo A::t('app', 'Account Type');
    echo A::t('app', 'Account Update Success Message', array('{name}'=>$accountName));
    echo A::t('news', 'Add News');

#### Modules Translation

It's recommended that each module will include it's own messages translation file. Such rule will provide the independency of each module and will allow to copy the message file into existing languages.
To make sure your message file will be copied into all existing languages in application, you have to add following definition if module `info.xml` file:

    <?xml version="1.0" encoding="utf-8"?>
    <install version="1.0" type="module">
        <files>
        ...
        <messages installationPath="protected/messages/*">
            <filename>testimonials.php</filename>
        </messages>
        ...
        </files>
    </install>