Server i18n Configuration

The server supports a wide range of localizable text settings. (See Text Properties.)

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

Localized text settings are key/value pairs that are passed to the server in a configuration file.

Localized text settings are case insensitive (regarding keys). For better readability localized text setting keys are written in camel case ( http://en.wikipedia.org/wiki/CamelCase) in the documentation and references.

Using Localized Text Configuration Files

Localized text settings are held in a configuration file. Localized files use the Java properties file format (see http://en.wikipedia.org/wiki/.properties) with some additional naming conventions.

In order to use a localized text settings file you need to specify where the server should load the file from using com.unblu.textoverlay

The value of the com.unblu.textoverlay configuration setting must point to a valid Java properties file. It can be a local file system path (absolute or relative) or any valid url supported by Java (i.e., http://<host>/<pathtoconfigurationfile>orfile:///etc/unblu/unblu.properties). We recommend always using forward slashes ("/") as the delimiter between path elements (also on windows systems) as using other delimiters (such as back slashes) only works if they are escaped properly.

How configuration settings are passed to the server is described in Configuration. In short, there are two options: Using System Properties (Using System Properties Directly) or using configuration files (Using Configuration Files).

# how to pass the location of the localized text settings file to unblu in a configuration file (extract of a configuration properties file)
com.unblu.textoverlay=/etc/unblu/unblu-text.properties

# how to pass the location of the localized text settings file to unblu using system properties (via the JAVA_OPTS OS environment variable, i.e. in Tomcat)
export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.textoverlay=/etc/unblu/unblu-text.properties"

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.

CAUTION: 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.)

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 language is declared using a .<lang> suffix at the end of the property key.

# 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 Multiple Localized Text Files

Instead of using a single localized text file, it is also possible to split localized text across multiple files. Multiple localized text files are specified using a coma separated list of file path or urls in the "com.unblu.textoverlay" configuration setting instead of a single value.

# 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"

This example specifies two localized text files:http://configurationserver/unblu/unblu-text.com and /opt/unblu/unblu-text.properties.

When using multiple localized text files, the ones that are defined later will always take precedence over the ones defined earlier.

In the example above this means that properties defined in /opt/unblu/unblu-text.properties will take precedence over properties defined in http://configurationserver/unblu/unblu-text.properties.

Using multiple localized text files can make sense, for instance, when there are multiple environments (i.e., prod, stage, development) that share most of the localized text settings but still need some individual configuration.

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>}, i.e., ${remainingMinutes}. Placeholders are case insensitive. For better readability placeholders are written in camel case in the documentation and reference.

# 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

Language Selection Algorithm

When unblu resolves a localized text property to the actual text, it first needs to compute the language that will be used.

Computing the effective language happens in two steps. First, the requested language is computed, then the effective language is computed.

Computing the requested language uses the following logic:

  1. If unblu is configured to use language cookies (use Language Cookie) AND a language cookie does exist, then the value of the language cookie is used as the requested language.

  2. If step 1 did not define the requested language AND unblu is configured to use the "x-unblu-locale" header (Use Locale Header) AND an "x-unblu-locale" header does exist, then the language attribute of the locale in the "x-unblu-locale" header is used as the requested language.

  3. If step 2 did not define the requested language AND unblu is configured to use the browser language (Use Browser Language) AND the Accept-Language HTTP request header does exist, then the Accept-Language header is used as the requested language.

Computing the effective language uses the following logic:

  1. If the requested language is set AND the requested language is one of the supported languages (Supported Languages) then the requested language is used as the effective language.
  2. If step 1 did not define the effective language then the default language (Default Language) is used as the effective language.

The behavior of unblu i18n is configurable using a set of configuration settings.

The most important configuration setting that is related to i18n is the com.unblu.textoverlay setting mentioned above. Besides this there are a number of additional settings, the most important of which are described briefly here.

Default Language

Use com.unblu.text.defaultLanguage to define the language that should be used if no language was provided in the context. (See Language Selection Algorithm above.)

Supported Languages

Use com.unblu.text.supportedLanguages to define the set of supported languages.

If the detected language from the context (see Language Selection Algorithm above) is not in the set of supported languages, then unblu will use the default language instead. (See Default Language above.)

Fallback Language

Use com.unblu.text.fallbackLanguage to define the language unblu will use if a certain localized text setting is not defined in the requested language. The default value for this setting is "en" for English and we do not recommended you change this because unblu products are guaranteed to provide a value for every localized text setting in English.

Use Browser Language

Use com.unblu.text.useBrowserLanguage to configure whether unblu should take into account the browser language (value of the Accept-Encoding HTTP request header) when calculating the requested language.

Use com.unblu.text.useLanguageCookie to configure whether unblu should take into account the value of the language cookie when calculating the requested language.

The name of the language cookie defaults to "x-unblu-lang"and can be configured using com.unblu.identifier.languageCookieName.

Use Locale Header

Use com.unblu.text.useLocaleHeader to configure whether unblu should take into account the "x-unblu-locale" locale HTTP request header when calculating the requested language.

Further Reading (Localized Text)

All available localized text settings are described in the Text Properties.

Read about unblu configuration in Configuration.

  • deployonprem

results matching ""

    No results matching ""