Internationalizing Error Messages and UI Copy

Learn how to set up custom, translated, or localized runtime error messages and other UI copy elements in the Akana Administration Console and Akana Gateway.

Note: The approach in this document is effective only for runtime error and informational messages and UI copy. It does not apply to alert messages defined in the database.

Valid in Version: 2019.0.12 and later

Table of Contents


The out-of-the-box copy for the Akana Gateway, both messaging and UI copy, is in US English. However, you can override the default for some types of messages and UI copy by setting up a new Java properties file and updating the platform settings to reference the new file.

In the properties file, you can define error message and UI copy keys and the applicable localization strings, set up as name/value pairs.

The steps are:

  1. Step 1: Create the Java properties file that specifies the new copy.
  2. Step 2: Upload the Java properties file to the /deploy folder of your installation.

Step 1: Create the Java properties file

To customize runtime error and informational messages and UI copy in the Akana Gateway, create a file using the name pattern and content specified below, and place it in the /deploy/ folder for the container.

File name

Use a file name that corresponds to the pattern com.akana.messages-{qualifier}.cfg, where {qualifier} is a unique string, such as a language code. For example, to internationalize error messages to Spanish and French, you might use these files:

  • com.akana.messages-es.cfg
  • com.akana.messages-fr.cfg

Properties in the file

The file is a normal properties file that contains the localization strings corresponding to the appropriate keys.

Use this custom property (one instance per custom properties file):

  • _locale: Required. Identifies the locale for the messages.
  • _basename: Required. Allows you to specify the resource bundle base name, which helps identify the resources in use. Helps reduce the likelihood of collisions, and speeds up lookups.

    To identify the resource bundle / resource collection base name, refer to the generated documentation. Use search to identify the copy, which is displayed in the context of the bundle. For more information, see Reference: Locating the copy for translation/localization below.

The example below sets the _locale property and modifies the message content for the login error message:

com.soa.console.loginError=Your login attempt was unsuccessful.

In your own file, replace the existing messages with new text.

For example, if you want to create French error messages, you could create a file named com.akana.messages-fr.cfg, paste the contents above, change the _locale value to en_fr, and update the message text with the translated copy. Add or remove messages as needed. When you have the translated content ready, upload the file to the correct location and test.

When you create the new properties file and add it to your implementation, messages are returned based on the basename and message key.

Back to top

Step 2: Deploy the files

Go to the /deploy/ directory for the container, and add the file or files you created in Step 1.

Back to top

View configuration changes

You can view the configuration changes that you've made, in the Akana Administration Console for the container.

To view configuration settings for messages

  1. Log in to the Akana Administration Console.
  2. Click the Configuration tab.
  3. On the left, under Configuration Categories, scroll down to find the com.akana.messages configuration category. You'll see the message settings. An example is shown below.

    Viewing the configuration settings

Back to top

Reference: Locating the copy for translation/localization

Valid in Version: 2020.1.0 and later

In version 2020.1.0, the _basename property is required in the Java properties file.

The default user interface copy and error message files are available as part of the platform generated documentation, to help you identify the basename, message name, and default copy.

The top-level file: Message Bundles (copy for internationalization)

In the top-level file, each entry includes two values: the bundle name (not used) and the basename. For example:

com.soa.console / ApplicationResources

You can click through on the basename and see the name and default copy for each message.

In your Java properties config file, use the basename, message name, and new message copy.

Back to top