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.

There are 3 types of multilingual support and for each one the files must be named as follows:

Generating A User Entered Language File

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

Open

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

Open

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 (without BOM).

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. Once the cache in the dashboard is cleared, the users will see the translated content. 

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 (for embedding).

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

Adding & 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.

The same format is used for the ‘messagesData’ file which has to be created manually but allows data elements to be translated such as category object values.

Card Charts

As part of the July 2024 (2024_07) release we introduced changes around how the key is constructed for the Card Chart types.

The key has been simplified by stripping HTML code and CSS styling in order to simplify the structure and readability. When generating a new language file, all the content related to card charts will be placed at the bottom of the language file. Each card chart will have its own block of key=value pairs, each separate by a comment that contains the name of the card chart.

Each card chart block will show the content from all hierarchies within the chart with the card chart content related keys having a prefix of the card chart title.

Example:

Key Explained:

Card+Three.Dev+and+Test=<div>Dev and Test</div>

• Card+Three - Encoded chart title

• Dev+and+Test - Encoded text value forming part of the key.

Localisation Files - Pre 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.