This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.

The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Localization

This page describes the steps required to use localization in your server installation.

The locale refers to the settings that may vary between languages or regions and countries. Besides the language, the locale may include such elements as currencies and date and number formats.

If your website has only one locale, localization amounts to little more than ensuring that Unblu uses the same one. Nevertheless, it is worth configuring the locale correctly. If, on the other hand, your website supports multiple locales, you will want to localize various UI elements, such as button labels or menu entries. You must also ensure that your customers are served the appropriate localized content.

This article describes how to meet each of these requirements.

General locale configuration

There are a number of configuration properties pertaining to localization that you should set regardless of whether you need to support a single locale or umpteen different locales.

Define a default locale for Unblu with the configuration property com.unblu.text.defaultLanguage. If your website only has one locale, set it here.
Define a fallback language for Unblu with the configuration property com.unblu.text.fallbackLanguage.

The fallback language is the one Unblu uses if the visitor’s locale (as determined by the method described below) is not supported by Unblu. We recommend using en as the fallback language as Unblu is guaranteed to provide English versions of all the texts it uses.
Specify which locales you intend to support by editing the list in com.unblu.text.supportedLanguages. If your website only supports one locale, you can remove all of the other locales from the list of supported languages.
Specify how you intend to identify a visitor’s locale. For this, use the configuration properties com.unblu.text.useLanguageCookie, com.unblu.text.useLocaleHeader, and com.unblu.text.useBrowserLanguage. If you set more than one of the properties to true, they will be evaluated in the order that they are listed in above.

You can find these configuration properties by searching for the term language on the account settings tab in the Account configuration interface. Alternatively, you can specify them in a configuration properties file.

Localizing text

Unblu offers a wide range of localizable text properties. You can review and edit these text properties on the translations tab of the entity (account, conversation template et al.) that they are related to.

Localized text properties can also be passed to the Unblu server as are key/value pairs in a properties file. The keys of localized text properties are case insensitive. For better readability, they are written in camel case in the documentation.

Localized text file format

Localized text files use the Java properties file format with some naming conventions. The Java properties file format is a simple text-based format that consists of key/value pairs that are delimited by the equals sign ("="). Every key/value must start on a new line. You can use \ to escape newlines or other special characters. Blank lines are ignored. Lines that start with # are comments. See http://en.wikipedia.org/wiki/.properties for more details about the Java properties file format.

The Java properties file must always be encoded using the ISO-88591-1 character encoding. Make sure any special characters are escaped properly. (See http://en.wikipedia.org/wiki/.properties.)

By default, Unblu uses a single file for all languages. Every localized text setting can occur multiple times in the same file (once for every supported language).

The target language of a text property is declared using a suffix equivalent to the language at the end of the property key:

Listing 1. Examples of language key suffix for English and German

# example of a localized text file with two settings, each for two languages (en,de)

tokendialog.title.en=Start support session
tokendialog.title.de=Support-Session starten

tokendialog.message.en=Please call the following telephone number for co-browsing
tokendialog.message.de=Für Co-Browsing rufen Sie bitte folgende Telefonnummer an

Using localized text properties files

Localized text propertes are held in files that use the Java properties file format with some additional naming conventions.

To use a localized text properties file, you must specify where the server should load the file from in the configuration property com.unblu.textoverlay. The configuration property must point to a valid Java properties file. The location of the file may be one of the following:

An absolute or relative path on the local file system, e.g. file:///path/to/text/properties/file/unblu-text.properties or ../../properties/unblu-text.properties
A valid URL supported by Java such as http://internal.mycompany.com/path/to/properties/file/unblu-text.properties

We recommend always using slashes (/) as the delimiter between path elements, even on Windows systems. Other delimiters such as backslashes (\) only work if they are escaped properly.

Using multiple files

You can spread the definitions of localized text properties over multiple properties files. This can be useful if you have different translators working on different languages, or if you want to share localized texts across environments that nevertheless require different localized texts in some circumstances. To use multiple localization properties files, provide a comma-separated list of file paths and/or URLs in the configuration property com.unblu.textoverlay. When using multiple localized text files, the files are evaluated in the reverse order of their occurrence

# example for using multiple i18n properties files (extract from a configuration properties file)
com.unblu.textoverlay=http://configurationserver/unblu/unblu-text.properties,/etc/unblu/unblu-text.properties

The example above specifies two localized text files:`\http://configurationserver/unblu/unblu-text.com` and \/opt/unblu/unblu-text.properties. Properties defined in \/opt/unblu/unblu-text.properties will be loaded before those defined in http://configurationserver/unblu/unblu-text.properties

If you provide multiple definitions of the same text property for the same locale, Unblu will use the last definition it finds.

Example

Suppose you have the following text properties files:

Listing 2. Text properties file text1.properties

# filename: text1.properties
com.unblu.agent.inbox.ui.titleInbox.en=My barren inbox
com.unblu.agent.inbox.ui.titleInbox.en=My empty inbox

Listing 3. Text properties file text2.properties

# filename: text2.properties
com.unblu.agent.inbox.ui.titleInbox.en=My overflowing inbox
com.unblu.agent.inbox.ui.titleInbox.en=My full inbox

Suppose further that the value of com.unblu.textoverlay is /path/to/text1.properties,/path/to/text2.properties. In that case, the title of the inbox in the Agent Desk will be "My empty inbox":

As mentioned in the previous section, the text properties files are evaluated in the reverse order of their occurrence in com.unblu.textoverlay.
Unblu evaluates the entire file, updating the value for the given text property each time it finds a new definition.

Text arguments

Some localized text settings support arguments (placeholders that will be replaced by some value at runtime). Supported arguments are described in Text Properties. If a setting supports arguments, then you need to specify placeholders for these arguments in your localized text settings. If you do not define placeholders, the value of the arguments will be missing in the output. Placeholders are formatted like this ${<placeholderName>}, e.g., ${remainingMinutes}, and their names are case insensitive. In the documentation, placeholder names are written in camel case for better readability.

# example of a localized text setting with arguments
com.unblu.hbworker.timeoutDialog.textTimeoutAhead.en=Your session will be timing out in ${remainingMinutes} minutes
com.unblu.hbworker.timeoutDialog.textTimeoutAhead.de=Ihre Sitzung wird in ${remainingMinutes} Minuten wegen Inaktivität geschlossen

Support for right-to-left (RTL) scripts

Some languages, such as Arabic, use a script that is written from right to left. This can have a considerable impact on your website beyond the text itself. For example, buttons and labels that refer to form fields should be positioned to the left of their related fields.

The configuration property com.unblu.text.useRtlDirection allows you to provide a consistent user experience on pages served by Unblu. Its value is a list of locales that should be interpreted as using an RTL script. The locales must be taken from the list of supported languages defined in com.unblu.text.supportedLanguages.

If the locale determined for a visitor is listed in the property, Unblu adds the attribute dir="rtl" to the HTML element of its visitor-facing UIs. This allows the visitor’s browser to position the various Unblu UI elements appropriately. The dir attribute is inherited by child elements, so UIs embedded in your website inherit the value of the dir attribute from the pages they are embedded in.

The position of the launcher button and the Visitor Individual UI on your pages is set with the configuration property com.unblu.siteintegration.ui.unbluUiPosition, independently of the script direction. If you want to position the launcher button and UI differently for different locales, you can specify different API keys for the different locales and then set the aforementioned configuration property for each API key.

The Agent Desk does not support a different page layout for languages written right-to-left, and the Account Configuration interface is only available in English.

Support for RTL scripts was added in Unblu version 6.33.0.