Localise an App

You can localise the UI labels in an app in multiple languages of your choice.

Localisation service

Appkit obtains the correct labels for a language by making calls to an Appkit translation service. The service provides a label in the chosen language, with a fallback to English if no translation exists for the label in the chosen language.

Loading translations

You can use the new <translations:localize> JSP tag to load a set of UI label translations into an app. The tag syntax is:

<translations:localize dictionary="dictionary" locale="locale" />
  • dictionary – Name of the resource bundle from which to load translations. This is also the first part of the name of each property file that contains translations.

    Default: translations

  • locale – Locale

    Default: en (English)

The dictionary and locale are used to find the file as follows:

  1. In src/main/resources, the Appkit translation service looks for a resource bundle named dictionary, for example, translations.

  2. Within the resource bundle, the translation service looks for property files named {resource}, for example, for the files translations_en.properties and translations_fr.properties.

Enabling translations

  1. Find label strings that need to be translated in the UI and identify the key names for the labels.

  2. Create translation property files and add them to a resource bundle in src/main/resources. For example, add translations_en.properties and translations_fr.properties to the resource bundle src/main/resources/translations.

    Edit the property files and include the label keys and translations. For example:

    In translations_en.properties:

    # translations_en.properties
    ...
    components.pagination.next = Next
    components.pagination.previous = Previous
    ...

    In translations_fr.properties:

    # translations_fr.properties
    ...
    components.pagination.next = Suivant
    components.pagination.previous = Précédent
    ...
    Note
    Some translations include variables. For example, components.response-statistics.showing is Showing {first} - {last} of {total} in English. Translations should retain the variables, though their order might differ. Labels can use <em> tags for emphasis, for example, More results like <em>{result}</em>.
  3. Add this taglib directive at the top of your app’s index.jsp:

    <%@ taglib prefix="translations" uri="/twigkit/translations" %>
  4. Add the Appkit <translations:localize> JSP tag inside the <head> element of your app’s index.jsp:

    <translations:localize locale="${param.locale}" />
  5. Add this rule to the url-rules.xml file:

    <!-- Language specific pages -->
    <rule>
        <from>^/lang/(.*)/</from>
        <to last="true">/index.jsp?locale=$1</to>
    </rule>
    Note
    You can modify other URL rules to suit your application logic. The `<translations:localize> JSP tag works the same.
  6. Restart your app.

  7. Verify that the translations are present by visiting pages in the app that should be in different languages.