This document describes version 5 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 5 ended on 22 November 2021. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu. |
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>;
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 server is described in Configuration. In short, there are two options:
-
Using System Properties Directly
-
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>}
, e.g., ${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:
-
If Unblu is configured to use language cookies and a language cookie exists, then the value of the language cookie is used as the requested language.
-
Otherwise, if Unblu is configured to use the locale header) and an the header
x-unblu-locale
exists, then the language attribute of the locale in that header is used as the requested language. -
Otherwise, if Unblu is configured to use the browser language and the header
Accept-Language
exists, then the value of that header is used as the requested language.
Computing the effective language uses the following logic:
-
If the requested language is set and the requested language is one of the Supported Languages then the requested language is used as the effective language.
-
Otherwise, the default language is used as the effective language.
i18n-Related Configuration Options
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-Language
HTTP request header) when calculating the requested language.
Use Language Cookie
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
. If another name is desired, it 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.