Internationalization

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

Clover and the underlying closure tools use the XMB message format.

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.

2. Copy and translate the generated xtb file to the target languages.
3. Use clover’s translations to select the xtb file used during compilation.

Example

Create a directory for the following example.

1. Create a subdirectory locale.

2. Create a test.js:

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

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.

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. 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.