i18n_l10n.doxy

/*!
\page i18n_l10n I18n & l10n
<div class="has-toc"></div>

# Internationalization & localization # {#i18n_main}

_Internationalization_ of an application requires to identify all language dependent
resources and make them exchangeable for the actual _localization_ into a specific
language. This includes __static__ and __dynamic texts__ as well as __images__.
Since images are referenced by their filename or represented as text (e.g. _base64_
encoded), it is sufficient to focus on text.

## Static text ## {#i18n_static}

Static text refers to text used in __application templates__ or __messages__ generated
while the application is executed. To keep the application code language agnostic
only so called _text identifiers_ are used in these places and the actual
translation is retrieved by calling the
\link wcmf::lib::i18n::Message::getText `Message::getText`\endlink method:

~~~~~~~~~~~~~{.php}
$textId = 'An error occured';

// retrieve the translation
$message = ObjectFactory::getInstance('Message');
$errorText = $message->getText($textId);

// use the translation
$ex = new Exception($errorText);
~~~~~~~~~~~~~

@note Implementations of \link wcmf::lib::i18n::Message `Message`\endlink
must return the _text identifier_, if no translation is found or the translation
is empty. This helps to simplify the translation process, if the default language
is used in _text identifiers_. In this case, no translation is required for the
default language.

If no language parameter is passed to the
\link wcmf::lib::i18n::Message::getText `Message::getText`\endlink method, the
returned translation will be in the application's __default user interface language__.
This language is determined in the following way:

1. Use the value of the `language` parameter of the `Message` configuration section
2. If not defined use the value of the global variable <code>$_SERVER['HTTP_ACCEPT_LANGUAGE']</code>

If parts of the text vary depending on the application state, it is necessary to
put  __variables__ into the text identifier. Variable names are `%0%`, `%1%`, ...
and they are replaced in the order of the values passed into the
\link wcmf::lib::i18n::Message::getText `Message::getText`\endlink method:

~~~~~~~~~~~~~{.php}
$textId = 'Logged in as %0% since %1%';
$parameters = array($username, $date);

// retrieve the translation
$message = ObjectFactory::getInstance('Message');
$loginMessage = $message->getText($textId, $parameters);

// use the translation
$view->setValue('loginMessage', $loginMessage);
~~~~~~~~~~~~~

### Template text ### {#i18n_static_tpl}

wCMF provides the `translate` plugin for embedding language dependent text into
_Smarty_ templates. The plugin is automatically included and used in the following
way:

~~~~~~~~~~~~~{.php}
{translate text="An error occured"}

{* with variables *}
{translate text="Logged in as %0% since %1%" r0=$login r1=$logindate}
~~~~~~~~~~~~~

### Localization ### {#i18n_static_locale}

Since \link wcmf::lib::i18n::Message `Message`\endlink defines the interface, it
needs concrete implementations to actually get the translations. The
\link wcmf::lib::i18n::impl::FileMessage `FileMessage`\endlink class retrieves
translations from the file system. It expects one file per language defining
a language dependent array that maps text identifiers to translations.
The language code (e.g. _en_) is used to identify the language of the translation.
The file must be named like <em>messages_</em>code.<em>php</em>,
the variable like <em>$messages_</em>code.

The following __examples__ show definitions for English (_en_) and German (_de_)
texts, where the array keys are the text identifiers used in the application and
the values are the translations in the appropriate language.

<em>messages_en.php</em>

~~~~~~~~~~~~~{.php}
$messages_en = array();
$messages_en['%0% selected'] = '';
$messages_en['Author'] = '';
$messages_en['Book'] = '';
~~~~~~~~~~~~~

<em>messages_de.php</em>

~~~~~~~~~~~~~{.php}
$messages_de = array();
$messages_de['%0% selected'] = '%0% ausgewählt';
$messages_de['Author'] = 'Autor';
$messages_de['Book'] = 'Buch';
~~~~~~~~~~~~~

@note Note that the text identifiers are in the application's default language
(_en_) and therefor no translations need to be provided.

The default __configuration__ of \link wcmf::lib::i18n::Message `Message`\endlink
is as follows:

~~~~~~~~~~~~~{.ini}
[Message]
__class = wcmf\lib\i18n\impl\FileMessage
localeDir = app/locale/
language = en
~~~~~~~~~~~~~

The parameter `localeDir` defines the directory where
\link wcmf::lib::i18n::impl::FileMessage `FileMessage`\endlink searchs for
translation files and the `language` parameter defines the application's default
language.

### Tools ### {#i18n_static_tools}

The \ref app "default application" ships with a tool for finding translatable text
and generating localization files from it. After installing the application
it is available under `http://localhost/wcmf-default-app/tools/locale/`.

The tool uses \link wcmf::lib::util::I18nUtil `I18nUtil`\endlink internally to
search for occurrences of

- <code>->getText('Text to translate', ...)</code> as used in
  <code>$message->getText('Text to translate', ...)</code> in PHP code
- `{translate:"Text to translate" ...}` as used in Smarty templates
- `Dict.translate("Text to translate", ...)` as used in the Javascript code of the
  \ref app "default application"

_Text to translate_ is supposed to be the message to be localized. The tool generates
one localization file for each language puts it into the appropriate directory.
It's capable of merging already existing translations into the newly generated
files.

The tool's configuration is defined in the file _config.ini_ in the tool's directory
and defaults to:

~~~~~~~~~~~~~{.ini}
[Application]
localeDir = app/locale/

[I18n]
searchDirs = {vendor/wcmf/wcmf/src/wcmf, app/}
exclude = {vendor, .git, .svn, test}
languages = {de, en}
~~~~~~~~~~~~~

## Model content ## {#i18n_dynamic}

Model content is initially created in the application's __default model language__,
which might differ from the _default user interface language_ (see \ref i18n_static).
Localization of the model content is done by using implementations of
\link wcmf::lib::i18n::Localization `Localization`\endlink. The interface defines
methods for loading and saving localized model content. The following code
demonstrates how to use it to get translated content:

~~~~~~~~~~~~~{.php}
$oid = new ObjectId('Book', 1);

// retrieve a localized entity instance
$localization = ObjectFactory::getInstance('localization');
$bookDe = $localization->loadTranslatedObject($oid, 'de');
~~~~~~~~~~~~~

### Localization ### {#i18n_dynamic_locale}

There are several strategies for storing localized versions of the content, all
having advantages and disadvantages regarding extensibility and performance. The
idea behind the
\link wcmf::lib::i18n::impl::DefaultLocalization `DefaultLocalization`\endlink
implementation is to keep the domain model clear of localization related attributes
by storing translations in a separate entity type. Using one entity type for all
content leads to more flexibility when extending the domain model.

The __translation entity type__ must have the following attributes:

- `objectid` object id of the translated entity (e.g. _Book:1_)
- `attribute` translated attribute (e.g. _title_)
- `language` the language code of the translation (e.g. _en_)
- `translation` the actual translation

The supported content languages are either defined in the `Languages` configuration
section (see below) or in the language entity type that is used by
\link wcmf::lib::i18n::impl::DefaultLocalization `DefaultLocalization`\endlink,
if the configuration section does not exist.

The __language entity type__ must have the following attributes:

- `code` language code (e.g. _en_)
- `name` language name (e.g. _English_)

The following __example__ demonstrates the creation of localized content
using the \link wcmf::lib::i18n::Localization `Localization`\endlink interface:

~~~~~~~~~~~~~{.php}
$oid = new ObjectId('Book', 1);

// retrieve the original entity instance
$persistenceFacade = ObjectFactory::getInstance('persistenceFacade');
$book = $persistenceFacade->load($oid);

// localize the instance
$book->setValue('title', 'Übersetzter Titel');

// save the translation
$localization = ObjectFactory::getInstance('localization');
$localization->saveTranslation($book, 'de');
~~~~~~~~~~~~~

The localization __configuration__ of the \ref app "default application" is the
following:

~~~~~~~~~~~~~{.ini}
[Localization]
__class = wcmf\lib\i18n\impl\DefaultLocalization
defaultLanguage = en
languageType = app.src.model.wcmf.Language
translationType = app.src.model.wcmf.Translation

[Languages]
de = Deutsch
en = English
~~~~~~~~~~~~~

In this example the _default model language_ is set to English and the
_language entity type_ is ignored, because the available languages are defined
in the configuration.
*/