Our website frameworks provide multi-language support to the products that run on them via internationalisation tokens. Tokens can be used in products wherever language specific text would be output. As content is returned to a user's browser, the website frameworks replace the tokens with the corresponding localised language string. This allows, for example, the same form to be published on multiple sites, rather than having to copy the form and translate it.
Localisation maps (lists of tokens and what they should be translated into) are managed within iCM using form shortcuts.
Note that the multi-language functionality should not be used to make otherwise fixed-text configurable. Do not use tokens simply to substitute a word or phrase (for example the name of an organisation) into an English sentence.
Subsite Locale
If you need to support multiple languages, you should create a subsite for each.
Each subsite has a locale. This determines which language will be used when tokens are replaced. The default locale of all GOSS products and sites is English -
In a subsite's configuration you can change the locale of the subsite using the "Locale" field, using, for example,
Token Format
Tokens look like this:
Tokens should obey the following formatting rules:
- Tokens are made up of a translation key (the bit that needs translating) between
i18n{} - Translation keys can only contain alphanumeric characters
a-z 0-9 or dots and must be in lowercase - Translation keys should be namespaced using dots
- A translation key must start with at least two alphabetic characters
- A number must not immediately follow a dot
- A translation key must not end with a dot
Token Parameters and Placeholders
If you are working server-side the token-matching pattern will also match tokens with parameters in the format
Parameters affect placeholders in the translated string, with the first parameter identified as
For example, looking up the key
Choice parameters are generally used with numbers to handle plurals. For example, the translation for the search result token could be
Tokens in Forms
Handlebars Templates
Using tokens in Handlebars templates can cause problems if you end up with three braces in succession, for example
This can be worked around using Handlebars' built in whitespace control, creating a token like
Button Labels
If you use an i18n token as a button label it will be substituted with the relevant language string. However, button handling depends on matching button labels to values specified in form scripts. When the form is submitted, the button label is sent back to forms service which does not "know" the translated value of the token and hence cannot compare it.
Token Management
Tokens can be managed using an iCM Form App shortcut. The form it uses is called I18NTOOLV1.
(The icon used in your installation could be different).
The shortcut opens a form that can be used to create, edit, delete, import and export tokens.
Searching
To search for an existing token, enter the full token that appears inside the braces, eg
From the search results you can edit or delete the token:
Pressing delete removes both the token and translations. Editing displays the token as read-only and lets you edit the translations.
Quick Search
The quick search brings back all of the tokens used in certain products. You can then edit or delete them (we don't advise deleting them as they are all in use by installed products).
Creating New Tokens
If you are developing content, like forms that use tokens, you can use the i18n tool to create new tokens.
Press "Create New Token" then enter your token and appropriate translations. The token will be saved to the iCM database and can be managed like any other installed token.
Import CSV
If you need to create multiple tokens you can import them from a csv. The file should include the token in the first column, then columns for each locale with the translations. The locale headings should match the locales of your websites. For example, a csv with tokens and translations for English and Welsh would look like this in Excel:
View Missing Translations
This button lists all token that have one or more missing translations.
Deploying Updates
Product localisation data (i18n tokens and translations) are automatically imported when a site build is deployed. The site build i18n installer will only import new or updated i18n data if:
- the i18n token does not already exist
- the last update to the i18n token's localisation value was by the i18n installer
If a GOSS-supplied i18n token's localisation value is updated by an iCM User, the localisation will not be overwritten by later installs. The installer checks per-token and per-localisation.
For example, if you were to manually update a Welsh localisation value, the installer would not update that value with a change in the product's Welsh value, but may still update the English value for the same token if that has not been manually updated.
Limitations
Some text is outside of the control of the platform so can't be handled by internationalisation tokens.
Media
Text in images (ie pictures of text) and videos cannot be localised, other than by creating alternative images and videos. Note that this type of non-text text is also really bad for accessibility so should be avoided anyway.
Form File Upload Fields
While some parts of the file upload field, like the label, can be localised, other parts, like the file upload button and the placeholder text, are set automatically by your browser. The English text in most browsers is "Choose file" and "No file chosen", but even this will vary per browser and operating system. Change your browser's language settings to see this text in another language.
Share this page
