RiskScape has built-in support for Internationalization (or i18n, as shorthand). This support allows users to use RiskScape in their native language (where available).
The Internationalization support in RiskScape is extensible, so you can add new translations if a particular language is not yet supported. This also allows you to override the default RiskScape messages and use a more domain-specific language, for example if you wanted to customize RiskScape for a specific subset of users.
RiskScape uses Java’s built-in internationalization support, but with a few extensions. RiskScape uses your system’s locale settings to search for the most applicable messages. A more detailed explanation of this system is published on Oracle’s Java Documentation
RiskScape’s extensions to this system allow you to provide your own set of translations (known as a Resource Bundle). The next section explains how to do this.
RiskScape’s internationalization support uses plain-text (UTF8-encoded) files, called Resource Bundles. These files contain the text for all user-facing messages in RiskScape. Each message is identified by a unique code, e.g.
riskscape.cli.usage = Welcome To RiskScape # ^ the code ^ the message
i18ndirectory in your RiskScape installation directory.
riskscape i18n --locale es_US --output-dir wip-dirsubstituting locale and directory as you want.
Translate the message text in the generated files.
Copy these translations into the
i18nRiskScape installation directory.
Test the translations by running RiskScape with the
user.countrysettings as below or by changing your system’s locale.
Generating translatable messages
i18n sub-command generates resource bundle (
.properties) files that contain all
of the messages codes in RiskScape, ready for translation.
riskscape i18n --output-dir=working-dir-for-translation --locale es_US
The default message text (i.e. English) is used in the generated files initially. You can now go through and modify the message text as needed. Note that it is important that you do not change the codes - only change the message text.
For help determining the appropriate
--locale value to use, see
Java 8 supported locales.
Note that you only need to specify the country portion of the locale if there are regional dialects
of the language you’re working with. Otherwise, it’s simplest just to use the language portion
of the locale. For example, if translating to Japanese, you can just use
--locale=ja rather than
To test your translations, copy your modified resource bundle (i.e.
.properties) files into RiskScape’s
If your system locale is already set to the target language, your new translations should appear when you run RiskScape, i.e.
Alternatively, if your system locale is not set to your target language, you can override the setting when you run RiskScape.
For example, to set the locale that RiskScape uses to
es_US, enter the following into your terminal prompt:
set JAVA_TOOL_OPTIONS=-Duser.language=es -Duser.country=US(Windows Command Prompt)
$env:JAVA_TOOL_OPTIONS="-Duser.language=es -Duser.country=US"(Windows PowerShell)
export JAVA_TOOL_OPTIONS='-Duser.language=es -Duser.country=US'(Linux/Docker)
riskscape --help to see your translations.
For more background on what setting the locale via
actually doing, refer to Java options.
RiskScape uses four different resource bundles for messages:
help- help text that describes how to use various parts of the RiskScape engine. For example, the descriptions displayed by
riskscape model info defaultcome from this file.
cli-help- help text for the various the RiskScape command line options. For example,
riskscape --helpuses the text from this file.
problems- text for reporting problems back to users to help them progress. For example, running an invalid command like
riskscape pipeline run bad-idresults in an error message that’s translatable.
labels- various labels for objects in RiskScape, e.g. what to call things when they’re printed out in the user interface. This includes the table headings such as id and description for commands like
riskscape model list.
Aside from the pointers listed here, In depth details of Resource Bundles can be found in the link to Java’s Internationalization documentation.
Resource bundle filenames
Resources bundles use the Java properties file format, and follow a few rules for how they are named. The name of the
file is important, as it contains locale
information that dictates how RiskScape will use it.
To add label translations for American English, the file would need
to be named
labels_en_US.properties. To add translations for American Spanish, the file would need to be named
labels_es_US.properties. To add translations for Spanish that aren’t country-specific,
the file would need to be named
RiskScape applies the following rules when deciding what text to display for a message:
The most specific message that can be found for your locale will be used. For example, RiskScape will check for a language and country match (e.g.
es_US) first before it tries to find just a language match (e.g.
If no match for your locale was found, RiskScape falls back to using the default locale (i.e. English).
If there are multiple matches for a message (i.e. you have added your own translation, and a message for the locale also exists in the built-in RiskScape code), then the user-provided translation will win.
If you are using RiskScape plugins, then the plugin’s message takes takes priority over the core/built-in RiskScape translations, but any user-provided translations will still win. Behaviour is undefined if the same message exists across multiple plugins.
Future versions of RiskScape may also allow translations to be provided from further external file locations.
Example using Windows
First, open up a terminal prompt. We recommend using Windows Command Prompt. Note that PowerShell requires more setup steps in order to display UTF-8 characters correctly.
Check the system locale that your terminal is using.
java -XshowSettings:locale .
If your current locale is not the target language you are translating to, then you have two options. Either:
Change the Windows system locale.
Change the locale that Java uses, i.e. enter the following command:
set JAVA_TOOL_OPTIONS="-Duser.language=es -Duser.country=US"
java -XshowSettings:locale . and check the locale now matches what you are translating.
Next, check the Windows code page
that is currently set in the terminal. Enter
chcp and it will display a number, e.g. 850.
Refer to the Windows documentation
for a list of supported code pages, and what these numbers mean.
RiskScape will set the console’s code page to 65001 by default, which is UTF-8 encoding. You can also set this by entering the command:
Now is a good time to check that any special characters in your target language will be
displayed correctly in the terminal. Create a new file in whatever plain-text editor
you prefer to use (e.g. Notepad). Add any characters that are specific to your target language
ā é î õ ü) and save the file as
temp.txt. Then from the terminal, display the file using:
They should hopefully be displayed correctly. For contrast, you could temporarily change
back to its original setting and see the difference it makes.
RiskScape output will use UTF-8 encoding by default. If the 65001 code page (UTF-8)
is not suitable for your target language for some reason, then you will need to override
RiskScape’s default encoding. To change the file encoding that RiskScape uses
(to code page 1252 in this example) use the following command:
Create the translation files
Create a working-directory folder to do the translations in.
This example will use
Then create the RiskScape resource bundle files for your target locale.
riskscape i18n --locale es_US --output-dir C:\RiskScape_Projects\US_Spanish Picked up JAVA_TOOL_OPTIONS: -Duser.language=mi -Duser.country=NZ Wrote 124 keys for help C:\RiskScape_Projects\US_Spanish\help_es_US.properties Wrote 12 keys for labels C:\RiskScape_Projects\US_Spanish\labels_es_US.properties Wrote 60 keys for problems C:\RiskScape_Projects\US_Spanish\problems_es_US.properties Wrote 102 keys for cli-help C:\RiskScape_Projects\US_Spanish\cli-help_es_US.properties
Make sure your target locale is already set in your terminal before running this command. That way, any existing translations in RiskScape will be preserved. For example, if there were already some Spanish translations in RiskScape, then these would be retained in the files generated.
Open the properties files in a plain-text editor (e.g. Notepad) and start translating the message text.
Although the files are plain-text, there are still some syntax rules you need to be careful with. Otherwise your translated message may not be displayed correctly.
Do not alter the message code (the bit on the left-hand side of the
If the translated text spans multiple lines, the last character on each line must be a backslash, i.e.
Some characters, like single-quotes (
') are escape characters. This means you always need to use two single-quotes (
'') where you want one single-quote (
') displayed in the message.
Test the translations
In order for RiskScape to use your translated text, your resource bundle files need to
be added to the
i18n sub-directory in the RiskScape installation directory.
If you followed the installation instructions, this directory will be
If you are unsure where your RiskScape installation directory is, the Upgrading RiskScape
instructions have some tips.
Copy your translated resource bundle files into the installation directory. E.g.
copy C:\RiskScape_Projects\US_Spanish\*.properties C:\RiskScape\riskscape\i18n\
Now when you run a RiskScape command, such as
riskscape --help or
riskscape model info default,
your should see your translated text appear.
As you add more message translations, remember to copy the updated
.properties files into
the RiskScape installation
Alternatively, you could modify the files in the
i18n folder directly, but it is a good idea
to still keep a backup copy of your work somewhere.
If you install a new version of RiskScape, you will need to copy your translated
files into the
i18n folder again. To avoid having to do this, we recommend
Committing completed translations back to the RiskScape codebase.
You do not have to translate every single message in the resource bundle. However, when you are finished, please delete any untranslated message/code pairs from the resource bundle files. RiskScape will display the default (i.e. English) text for any messages that are missing from your resource bundle.
Example using Docker
Note that if you are using a RiskScape docker image to generate the i18n files, then you’ll need to mount the directory you’re working in as a volume. Otherwise any modifications you make to the i18n files will be lost when you exit the docker session.
For example, to run the RiskScape docker image (on Linux) and mount your current working directory as a volume, use:
docker run --rm -it -v$PWD:/home/riskscape/i18n riskscape-cli
For a Windows user, the same command would look like:
docker run --rm -it -v%cd%:/home/riskscape/i18n riskscape-cli
Next, create the i18n resource bundle files in the directory you mounted:
riskscape i18n --locale es_US --output-dir /home/riskscape/i18n chmod o+w /home/riskscape/i18n/*.properties
By default, any files that were created within a docker session are read-only.
chmod command makes the resource bundle files writable for any user.
This means you can edit the i18n files from outside the docker session,
using your editor of choice.
Once you have made changes to resource bundle files, in your docker session copy the edited files into the RiskScape installation directory:
cp /home/riskscape/i18n/*.properties /opt/riskscape-cli/i18n/
Then to test the translations, make sure your locale is set appropriately
and run a
riskscape command to display the help text, e.g.
export JAVA_TOOL_OPTIONS='-Duser.language=es -Duser.country=US' riskscape --help
Committing completed translations
Once you have completed your translation, we recommend committing your translated text back to the RiskScape codebase. To do so, you can simply email your resource bundle files to firstname.lastname@example.org.
The reason we recommend this is because future changes to the RiskScape code may alter the message codes in the resource bundle files. If this happens, then some of your translated text may no longer be displayed correctly on future versions of RiskScape.
If your translations are committed to the RiskScape codebase, then the resource bundle files will live alongside the RiskScape code. This means that if a i18n message code changes in future, then your resource bundle files will also be updated, and your translation will continue to work.