###################
Internationalization
###################


Clover has features to help developers produce translated versions of their applications.

Clover and the underlying closure tools use the `XMB message format <http://cldr.unicode.org/development/development-process/design-proposals/xmb>`_.

The XMB format is a key-value pair list. It has a mechanism for named placeholders, with descriptions and examples. 


Extracting messages
###################

Clover has a command to extract messages from the application::
    
    clover messages <config> <id>

This command will extract all messages (defined using goog.getMsg) from the application to standard output.

General workflow
################

You should have a configuration file set up and a directory to store translation files (eg, "locale").

1. Extract all of the applications messages to an xtb::

    clover messages <config> <id> -o locale/en.xtb

   To reduce friction when translating applications, you may use tools to merge the extracted XTB into an existing XTB.

..  TODO: List tools that work with XTBs.

..  TODO: Even better, support po format.

2. Copy and translate the generated xtb file to the target languages.

3. Use clover's :ref:`option-translations` to select the xtb file used during compilation.


Example
########

Create a directory for the following example.

1. Create a subdirectory `locale`.

.. highlight:: javascript

2. Create a test.js::
    
    /** @desc context menu - make a duplicate of the selected block */
    MyProject.MSG_DUPLICATE_BLOCK = goog.getMsg("Duplicate");

.. highlight:: yaml

3. Create a clover.yaml::
    
    paths:
    - .
    
    inputs:
    - test.js
    
    output: build/app.js
    translations: locale
    
4. Create a clover-fr.yaml::
    
    inherits: clover.yaml
    language: fr
    output: build/app-fr.js
     
5. Extract the messages::
    
    clover messages clover.yaml -o locale/en.xtb

6. Copy the generated locale/en.xtb to locale/fr.xtb.

.. highlight:: xml

7. Translate the `<translation>` element in locale/fr.xtb; replacing "Duplicate" with "Dupliquer". The file should look like this (the translation id will differ)::
    
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE translationbundle SYSTEM "translationbundle.dtd">
    <translationbundle lang="fr">
      <translation id="5213219513082471002">Dupliquer</translation>
    </translationbundle>
    
8. Compile the application with the french configuration file::
    
    clover build clover.yaml
    
The translated application will be in `build/app-fr.js`. All messages in the file will be replaced with the french versions specified in `locale/fr.xtb`.


Complex messages
################

Placeholder elements offered by the XMB are limited to simple value replacement. Messages must correspond 1:1 with those of English. In addition, goog.getMsg calls are compiled to strings, making dynamic replacement impossible. 


For more complex patterns, consider using the `goog.i18n.MessageFormat class <http://docs.closure-library.googlecode.com/git/class_goog_i18n_MessageFormat.html>`_. passing a message (using goog.getMsg) as the `pattern` argument.

The MessageFormat format is described in more detail at http://userguide.icu-project.org/formatparse/messages.