Solprovider Lenya Kongregate Registration for Free Flash Games and Chat with solprovider

Language Translation using i18n

i18n is the international abbreviation for "internalization". i18n is used to easily translate to multiple languages.

The easiest method for using i18n is adding tags around text needing translation, and adding the text to the language files.

Adding tags

There are several methods for adding the i18n tags. The easiest and most popular is to add the tags around existing text:
<i18n:text>This should be translated.</i18n:text>
The advantage are:
1. The text reads correctly.
2. The text is translated to "untranslated" if it is missing from a language file, making testing/debugging easy.
The disadvantages are:
1. The text is used as the key in the language files, and must be added to every language file.
2. The text must NEVER BE CHANGED. Any maintenance must be done in the language files.

The second method is to add i18n as keys:
<i18n:text key="keyForThisText"></i18n:text>
<i18n:text key="keyForThisText"/>

The advantages are:
1. Nothing appears if the key is missing from a language file, allowing the phrase to only appear for certain languages.
2. Maintenance is obviously in the language files.
The disadvantages are:
1. It is difficult to debug because nothing is displayed if the translation is missing.
2. The text does not read correctly.

The third method combines the first two:
<i18n:text key="keyForThisText">This should be translated.</i18n:text>
The advantage are:
1. The text reads correctly.
2. The key is used for translation, solving the "never changing the text issue".
2. The translation is not required for the default language file, since the text is used as the default, rather than "untranslated".
The disadvantages are:
1. It is not obvious whether maintenance is in the language files. For the default language, it depends on whether the key exists.
2. Debugging requires noticing the wrong language is displayed, rather than the easy to notice "untranslated".
This method is probably the best, but requires extra thought. If your policy is that every key is in every language file, then maintenance will be in the language files. That policy is good because automation can notice missing keys. If your policy is to use the default text rather than the key for the default language, then automation is more difficult, and maintenance requires finding the text where it is used, which may be content, XSL, XSP, JS, JSP, and Java files. It is recommended to keep the language files synchronized. You may want to add "(UNTRANSLATED) " to your default values for easier debugging and maintenance:
<i18n:text key="keyForThisText">(UNTRANSLATED) This should be translated.</i18n:text>

A final method is used for properties of other tags:
<input i18n:attr="value" type="submit" value="Submit"/>
<mytag i18n:attr="myProperty" myProperty="Display this"/>

This allows translating properties. The key used for translation is the value of the property ("Display this" in the second example.) It is treated like the first method, so if the key is missing from a language file, it shows "untranslated".


There are several formats used for keys:
1. Keys for properties are typically the standard value for that property:
<input i18n:attr="value" type="submit" value="Submit"/>
<input i18n:attr="value" type="submit" value="Save"/>

The keys are "Submit" and "Save". This should also be used for most short (1 or 2 words) text.

2. Some keys use dashes:
<message key="login-to-pub">LOGIN to the {0} Publication</message>
Dashes tend to be used in XSL uses of i18n.

3. Some keys use periods:
<message key="lenya.imageupload.title">Insert Image</message>
Periods tend to be used for JS, JSP, XSP, and Java uses of i18n.

4. Underscores are also allowed:
<message key="my_key">My text</message>
Underscores are not used by Lenya. They could be used to distinguish publication-specific keys.

Keys can include periods, dashes, underscores, and spaces. Lenya mixes the various styles, and often uses i18n without keys. It is always the developer's choice, but consistency makes maintenance easier. It does not make sense to worry where the key was first used, because once a key is added, it should be used in every file type. Have fun, but check the global and publication language files to reuse a key before adding your own.

More documentation The official documentation is Cocoon's i18n Transformer.

<< i18n File Priorityi18n Variables >>

Contact Solprovider
Paul Ercolino