Adding Support for Additional Languages

This section defines the currently localized languages that are supported in the ActivID CMS User Portal.

It also provides information about the localized file structure, what you need to do before you can add a new language, and how you can add a new language.

Prerequisites: You must first install ActivID CMS before attempting to use or customize the ActivID CMS User Portal. For more information, refer to Installing ActivID CMS.

Localized Languages

The ActivID CMS User Portal is localized in the following languages:

English (US)
French
German
Italian
Japanese
Polish
Portuguese
Spanish

Note: The list of localized languages is the default included in ActivID CMS.

The ActivID CMS User Portal Web pages consist of software code that refers solely to the required content using key/value pairs. When the system displays a Web page, it gets the keys from this code, and searches the files using the set of keys to retrieve the corresponding titles and text strings.

Localized File Structure

Localized messages are stored as key/value pairs, which are separated by an equal sign (=) in the corresponding .properties files. Remember the following about key/value pairs:

Keys are unique inside each file.
Values contain the exact text that is actually displayed in each Web page.

The following is an example of a key/value pair:

Copy

cardholder.cardholderChangePIN.18=Your smart card PIN has been successfully changed.

Localization Process Properties Files

The localization process is based on .properties files per each localized language, which are divided and located in the following directories:

cms_install_dir/cms_portal/WEB-INF/classes/cardholder

This directory contains the .properties files that are specific to the ActivID CMS User Portal.

cms_install_dir/cms_portal/WEB-INF/classes/common

This directory contains the .properties files used by both the ActivID CMS User Portal and the ActivID CMS Operator Portal.

For each localized language supported in ActivID CMS, there are .properties files that are duplicated and localized (or translated) into the corresponding language. The main differences are:

A suffix is added to each file name (consisting of the local and country ID).
The value (key/value pair) corresponding to the message that displays is translated in each file into the appropriate language.

For example:
Copy
```
cardholder.cardholder_insert.16=Please insert your card in the reader.
```
where the following key/value is represented as:
- Key—cardholder.cardholder_insert.16
- Value—Please insert your card in the reader.

Adding a New Language

By default, the ActivID CMS User Portal Web pages are displayed in English. The files that contain the English text strings have no suffixes. For example, the sample.properties file contains the English text while the sample_fr.properties file contains the French text.

The ActivID CMS User Portal text file localization process strictly adheres to the Oracle^® standard as defined in: https://www.oracle.com/technetwork/java/javase/documentation/java11locales-5069639.html

The naming convention for the ActivID CMS User Portal localization files observes the following format:

filename_standardForLocale_standardForCountry.properties

where:

standardForLocale = _xx = “_” plus two characters in lowercase for the standard for locale.
standardForCountry =_XX =“_” plus two characters in uppercase for the standard for country (optional).

As you add a new language, you must apply the following rules:

You must add one set of message files for each additional language that is supported.
Duplicated files must have the same name as the original files, plus you must add a suffix that indicates to which locale (and optionally to which country) these files apply.
Any keys in files to the left side of the equal sign (=) must remain the same. Only the values to the right side of the equal sign can be or should be translated.

The following two examples show the process for:

Adding a version of a .properties file in another language (French),
Adding a version of a .properties file in another language (French) that is localized for another country (Switzerland).

Note: You must restart the Microsoft Internet Information Services (IIS) server for any changes to take effect.

Example 1: Adding a French Version

To add a French version of the cardholder_insert.properties file, you must complete the following steps:

Duplicate or copy the file.
Rename this copy to cardholder_insert_fr.properties (where _fr stands for the French locale).
Edit the French version of the file, and translate all values. Make sure that you do not update the keys.

Example 2: Adding a French Version Localized for Switzerland

To add a French version of the cardholder_insert.properties file that is localized for Switzerland, you must complete the following steps:

Duplicate or copy the file.
Rename it to cardholder_insert_fr_CH.properties (where _fr stands for the French locale and _CH stands for Switzerland).
Edit the cardholder_insert_fr_CH.properties file, and translate all values. Make sure that you do not update the keys.

About Character Encoding

ActivID CMS only supports .properties files that have been encoded using ASCII with Unicode-encoded escape codes (\udddd notation). No other character encoding is supported.

If a different character encoding is used, the ActivID CMS User Portal might not interpret these correctly and display instead random characters in place of the intended text.

Edit the .properties files using a text editor (for example, Notepad) using native encoding. Then use the native2ascii tool to convert the files back from your native character encoding (such as Shift JIS or UTF-8) to ASCII with Unicode-encoded escape codes.

The native2ascii tool is part of the Java Development Kit™ (JDK) and can also be used to translate from Unicode-encoded escape codes to native encoding.

For more information, refer to the Oracle JDK documentation.