Unblu Server i18n Configuration

1. Introduction

The unblu server supports a wide range of localizable text settings settings (see Unblu Server Localized Text Reference). This page describes the steps required to use unblu localization in your server installation.

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

Unblu 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.

2. Using localized text configuration files

Localized text settings are held in a configuration file. Unblu 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 unblu server should load the file from using the "com.unblu.textoverlay" configuration setting (see 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> or file:///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 unblu server is described in Unblu Server 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"

3. Localized text file format

Unblu localized text files use 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. Please have a look at http://en.wikipedia.org/wiki/.properties for more details about the java properties file format.

CAUTION: 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 settings 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

4. Text arguments

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

# example of a lolcalized 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

 

5. 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 a "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 (user 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.

6. i18n related configuration options

The behaviour 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 is a number of additional settings, the most important of which are described in short here.

6.1. Default language

The configuration setting "com.unblu.text.defaultLanguage" (see com.unblu.text.defaultLanguage) defines the language that should be used if no language was provided in the context (see language selection algorithm above).

6.2. Supported languages

The configuration setting "com.unblu.text.supportedLanguages" (see com.unblu.text.supportedLanguages) defines 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).

6.3. Fallback language

The configuration setting "com.unblu.text.fallbackLanguage" (see com.unblu.text.fallbackLanguage) defines 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 it is not recommended to change this because unblu products are guaranteed to provide a value for every localized text setting in english.

6.4. Use browser language

The configuration setting "com.unblu.text.useBrowserLanguage" (see com.unblu.text.useBrowserLanguage) configures if unblu should take into account the browser language (value of the Accept-Encoding HTTP request header) when calculating the requested language.

6.5. Use language cookie

The configuration setting "com.unblu.text.useLanguageCookie" (see com.unblu.text.useLanguageCookie) configures if 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 the "com.unblu.identifier.languageCookieName" setting (see com.unblu.identifier.languageCookieName).

6.6. Use locale header

The configuration setting "com.unblu.text.useLocaleHeader" (see com.unblu.text.useLocaleHeader) configures if unblu should take into account the "x-unblu-locale" locale HTTP request header when calculating the requested language.

7. Further reading

All available localized text settings are described in the Unblu Server Localized Text Reference.

Read about unblu configuration in Unblu Server Configuration.

 

 

 

 

How can we help?

Chat with us and we will take you through our site!

Read about how we use cookies and how you can control them by clicking "Cookie Settings." If you continue to use this site, you consent to our use of cookies.