Contact usRequest a demo

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’re listed in above.

You can find these configuration properties by searching for the term language on the account’s 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 Texts tab of the entity (account, conversation template et al.) that they’re 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’re 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 are 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 uses 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 don’t define placeholders, the value of the arguments will be missing in the output. Placeholders are formatted like this: ${<placeholderName>}, for example ${remainingMinutes}. 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

Localizing accounts, conversation templates, named areas, and teams

Some UIs display the names of accounts, conversation templates, named areas, or teams. For example:

  • The Agent Desk lists the names of conversation templates in the plus menu plus menu icon for agents to start different types of conversation.

  • The concierge onboarding step "Choose named area" uses the names of named areas as button labels in the visitor UI.

These UI elements can be localized to create a better user experience. You can add translations of the element’s name and description (where available) in the Account Configuration interface. For guidance see Translations in the Account Configuration interface guide.

Once you’ve added translations to the entities, you must configure Unblu to use them. You do so with the following configuration properties in the ACCOUNT scope:

The possible values are:

LOCALIZED_NAME

This is the default value for each of the configuration properties listed above. If there is a translation available in the user’s language, Unblu uses it as the entity’s display name.

TECHNICAL_NAME

This is the name you give an entity when you create it.

The technical name serves as a fallback value for the display name: if no translation is available in the user’s language, Unblu uses the technical name as the entity’s display name.

LOCALIZED_DESCRIPTION

The translation of the description of the entity. If a translation is available in the user’s language, Unblu uses it as the entity’s display name.

There’s no fallback value for this option.

TECHNICAL_DESCRIPTION

This is the description you give an entity when you create it.

There’s no fallback value for this option.

Support for right-to-left (RTL) scripts

Some languages, such as Arabic, use a script 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’re embedded in.

The position of the launcher button and the Floating Visitor 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 doesn’t support a different page layout for languages written right-to-left, and the Account Configuration interface is only available in English.

See also