Multilingual

This section will provide detailed instructions on how to setup, use and edit localisation.

When *localisation* is referred to this means the ability to provide multi-lingual support for the application.

Generating a language file

Firstly, you need to login to the dashboard and open the right-hand side menu and select ‘Generate language file’.

Open

Pressing ‘Generate’ will create a language file which will contain all the user entered information that can be translated.

Open

Once the generation is done the name of the new file will be presented to you and it will be saved to the install directory of the Dashboard.

Making the files work as a custom locale

Once the file has been generated there are a few steps you must take. First, head to the localisation folder:

*INSTALL_DIR*/tomcat/webapps/panMISDashboardResources/locale

The messages files contained within this directory are property files containing key / value pairs. Editing the value portion of the property will change the text which is displayed in the application. All files must be UTF-8 encoded.

To add new localisations to the application, create a copy of the 'messagesStatic.properties' file in the locale folder. This file needs to be renamed to include the relevant locale e.g. ‘messagesStatic_pt_PT.properties’. This file can then be edited to change the language for various parts of the Dashboard without needing a restart of the system.

The same can be achieved with the user generated language file by changing the name of the file to reflect the relevant locale e.g. ‘messagesUserEntered_pt_PT.properties’ and moving this file into the locale directory. This file when first created requires a full restart of the dashboard server.  Subsequent changes to the file do not require a server restart, but will require a supervisor to clear the cache in the dashboard once the files are updated. Once the cache in the dashboard is cleared, the users will see the translated content.

You also need to edit 'available-languages.properties' in locale to enable the Dashboard to pick up your new language files - e.g. add Portuguese=pt_PT. This will then create a drop down menu for the language on the login screen of the Dashboard.

The available-languages.properties file is ISO-8859-1encoded, so extended characters like ê could have issues retaining their UTF-8 presentation. Now, the file has been updated to use the Unicode escape sequence equivalent of \u00EA instead which will not get re-encoded and displays consistently as expected.

Now, any changes made to the 'messages*' language file with the code corresponding to the language you select when logging in will be reflected in the Dashboard. An alternative to selecting your desired language from the drop-down on the login page is to change the URL language query to match the locale e.g. change 'lang=en_GB' to 'lang=pt_PT'. Taking 'en_GB' as an example, the 'en' represents the language whilst the 'GB' represents the country - both parts are important.

When logging in, you can either force the URL to the desired language.

or select the language from the drop-down at the bottom of the Login page.

Adding and updating translations

As of the March 2023 release of The Dashboard, the way that the keys are generated for the ‘messagesUserEntered’ file has changed. For versions prior to this, see the section below entitled “Localisation files prior to the March 2023 release“.

The format for the ‘messagesUserEntered' is that each key/value pair occupies its own line and the key and value are separated by an equals sign ('='). The key is generated from the original value of the translatable text e.g. if the original name of a chart is “Number of Charts“ then “Number of Charts” is encoded and used as the key. This means that even if there are multiple, identical translatable values present on The Dashboard there will only be one key/value pair in the language file and updating the value component of this with your desired text will provide translation for all of those areas.

If you add new content to the Dashboard that contains translatable fields or update the value of an existing translatable field you will need to add new key/value pairs to the ‘messagesUserEntered’ file. The key is encoded in ‘Form URL’ format (application/x-www-form-urlencoded) and is human-readable for English alphabet characters so you might be able to derive it from the new content yourself. Another way of getting the new key/value pair is to:

1. Generate another language file in the same manner as you did above

2. Find the line matching the new/updated content

3. Copy that key/value pair line into the file that holds the rest of your translations

When the file is initially generated, it is sorted alphabetically with no duplicate values present. When manually inserting a new key/value pair we would recommend that you conform to this standard to avoid potential confusion in the future. Removal of the old key/value pair is not required. If you choose to leave it within the file then any future values that match it would be translated with no additional effort when the Dashboard next restarts.

Localisation files prior to the March 2023 Release

Parts of the text within the dashboard display in priority order which the localisation also follows. For example, Chart Titles can be set from the chart title section of the edit chart screen as well as the attribute section of the Edit Chart screen. The following sections explain the order for different parts of the dashboard:

Category name

• Label from language file e.g., MIS_CATEGORIES.LABEL.b8b9470f3d714bfd8f337348d5ad55fc=This value will replace the Category LABEL

• Label from app

• Name from language file e.g., MIS_CATEGORIES.NAME.b8b9470f3d714bfd8f337348d5ad55fc=This value will replace the Category NAME

• Name from app

Chart Titles

• Language file hierarchy level title e.g., MIS_DEFINED_CHARTS.f1924dcb7dfa492aa1e7711b48cbb2dc.MIS_HIERARCHIES.49e94b60841a43a58333d6db0bc39efd=This value will replace the drill level specific title

• App hierarchy level title (drill level specific title)

• Language file chart title e.g., MIS_DEFINED_CHARTS.f1924dcb7dfa492aa1e7711b48cbb2dc=This value will replace the overall chart title

• App chart title

• Top level title replaced

x-axis, y-axis, y2-axis and legend override

• Language file chart override e.g. MIS_DEFINED_CHARTS.ca86a1141a51454ca99b9854c770919f.MIS_CHART_COLUMNS.070b630eaa2843f6b3260f12db40c27a=This value will replace the overrides (for x-axis, y-axis, y2-axis or legend override) in the chart

• App chart override

• Language file object label override e.g. MIS_COLUMNS.LABEL.d0c280131cdd4244b46c0737938ae776=This value will replace the data connection object LABEL in the chart

• App object label

• Language file object display name override e.g. MIS_COLUMNS.LABEL.d0c280131cdd4244b46c0737938ae776=This value will replace the data connection object NAME in the chart

• App object display name

Category objects (category filters)

• Language file object label override e.g. MIS_COLUMNS.LABEL.d0c280131cdd4244b46c0737938ae776=This value will replace the data connection object LABEL in the chart

• App object label

• Language file object display name override e.g. MIS_COLUMNS.LABEL.d0c280131cdd4244b46c0737938ae776=This value will replace the data connection object NAME in the chart

• App object display name

• Select all value - can be overridden by in a separate section of the language file e.g., MIS_CATEGORY_OBJECTS.SELECT.ALL.235f1c4ade104574a379dce979b12455=This value will replace that on the category object when all is selected

It is also important to note that any changes made to the dashboard e.g., adding a new chart, making a change to existing charts or changing any texts will require the user to re-generate the language file. This new language file will include the changes made in the dashboard. The user then can merge the two and include the changes found in the new language file.