Back to Search Back to Search Results

Translation Support

Managing site translation in Titania Delivery involves using FreeMarker definition files containing the translations, and a mechanism for finding the strings in the current language.

The Titania Default portal theme contains a pages/i18n folder. This folder contains utility templates to be imported into other pages for purposes of translating the User Interface into different languages. Specifically, the pages/i18n/strings.ftl template exposes a getString() function that takes an English string as a parameter, and returns a translated string in the user's current language if one is available. In addition, the User Interface exposes the ability for the user to change the current interface language from among the available languages.

To use a translated string in a page, simply load it through the getString() function, e.g.

${getString('English String')?html}

Adding Strings

The language files in the pages/i18n folder are named for specific locale codes. These files contain simple Freemarker hashes of the English string mapped to the translation of that string.

<#assign strings = {
  "Learn about Titania": "En savoir plus sur Titania",
  "Learn about Titania Delivery": "En savoir plus sur Titania Delivery",
  "Powered by Titania Delivery": "Optimisé par Titania Delivery",
  "Links": "Liens"
}/> <#-- lots more, but this is an example -->

To add strings for a particular language, add them to this file.

To add new languages

  1. Create the new translation file, named for the locale code of the language, and load it into the pages/i18n folder.
  2. Update strings.ftl to import the new file, and add it to its stringlib collection.

Parameterized Strings

The getString() function supports parameterized strings using $1. $2, etc. for the parameters. For example, from the French translation file:

"Page $1 of $2": "Page $1 sur $2"

When requesting this string, you pass an array of parameter values to the getString() function, e.g.

${getString('Page $1 of $2', ['1', '10'])?html}
<#-- Translates to "Page 1 sur 10" -->

Assuming the translation includes the parameter tokens, they will be replaced with the specified values. You can escape dollar signs with a backslash (\), e.g. getString("\$2 dollars").

Determining the User's Language

The strings.ftl template uses the following algorithm to determine the appropriate language for the user.

  1. If there is a td.lang browser cookie, its value is used. The default portal theme includes a menu in the header allowing the user to manipulate this cookie.
  2. Otherwise, if the request specified a Content-Language header, that value is used. Most browsers send this header specifying the default language of the user's system.
  3. Otherwise the language is assumed to be English ("en").

Debugging Translations

The getString() function will look for a URL parameter specifying debugLang=true. If it is present, then the strings it returns will be marked.

  • If a string for the given input was found, the result will be wrapped in {s} and {/s}.
  • If a string was not found, it will be wrapped in {MISSING_STRING} and {/MISSING_STRING}.

This will allow you to easily identify strings that are correctly translated, strings that are missing from translation files, and strings that are not being rendered through getString() (because they will not be marked at all).

Translating Generated Text in XSLT Transforms

All of the default theme's XSLT stylesheets take a defaultLang parameter used to control the rendering language, and have a function similar to the Freemarker getString() function for loading translations. See Localizing Generated Text for full details.

Parent topic: Page Templates