Setting the visitor-side locale

Unblu uses a visitor’s locale primarily to ascertain which language to display the UI in. It then resolves button labels, menu entries and the like to the appropriate localized text property.

Determining a visitor’s locale always proceeds in the same order:

If you use the Unblu snippet, Unblu will check
1. the Unblu Visitor JS API configuration,
2. the document locale, and
3. the request locale,
in that order. The last two of these steps each consists of several steps.
If your website doesn’t include the Unblu snippet, Unblu will only check the Visitor JS API configuration.

The details of the various steps are outlined in the sections below.

Note that Unblu doesn’t necessarily carry out each step listed above. Locale resolution ends once Unblu has been able to determine a locale for the visitor.

Determining the locale with the Unblu snippet

The various checks Unblu executes to determine the locale of a visitor to your website are discussed in the order in which they are carried out.

Checking the Unblu Visitor JS API configuration

If you use the Unblu Visitor JS API to integrate Unblu into your website, you can set the locale when you initialize the JS API.

Listing 1. Setting the locale to Swiss High German with the Unblu JS API

const api = unblu.api
    // Configure the Unblu JS API
    .configure({
        // Include other configuration properties as needed
        // Set the locale
        locale: "de-CH"
    })
    // Initialize the API
    .initialize();

Initializing the API also loads the JavaScript that would otherwise be included by the Unblu snippet. You should therefore normally not include both the Unblu snippet and the Visitor JS API on a page. If you have reason to do so anyway, and you want to set the locale via the Visitor JS API configuration, you must ensure that the JS API is initialized before you load the Unblu snippet.

Checking the document locale

If you don’t use the Visitor JS API, Unblu will first attempt to determine the visitor’s locale by checking the contents of the document being loaded:

If the html tag has the custom unblu_locale attribute, Unblu will use that value. Given the tag below, the locale would be set to "Swedish":
```
<html unblu_locale="sv">
```
If the html tag has no unblu_locale attribute, but it does have a lang attribute, Unblu will use that value. Given the tag below, the locale would be set to "Serbian":
```
<html lang="sr">
```
If the html tag has neither an unblu_locale nor a lang attribute, but it does have an xml:lang attribute, Unblu will use that value.

Given the tag below, the locale would be set to "Slovenian":

<html xml:lang="sl">

Finally, if none of the attributes mentioned above are present, Unblu will use the value of the unbluLocale query parameter (if present). For example, given the html tag <html>, the following URL would set the locale to "Polish":
```
https://www.mycompany.com/contact/?unbluLocale=pl
```

The locale specified must evaluate to one of the values defined in the configuration property com.unblu.text.supportedLanguages. Invalid locales and locales not supported by Unblu will result in the fallback language being used. If the html tag includes multiple locale attributes, only the first one is evaluated. Thus, given the html tags below, the visitor’s locale will be set to the fallback language:

<!-- The language zh-yue (Cantonese) is currently not supported by Unblu -->
<html unblu_locale="zh-yue">

<!-- The language "foo" is not a valid locale string -->
<html lang="foo">

<!-- The language zh-yue (Cantonese) is currently not supported by Unblu, so Unblu
uses the fallback language. The attribute "xml:lang" is never evaluated. -->
<html unblu_locale="zh-yue" xml:lang="sv">

<!-- The language "foo" is not a valid locale string, so Unblu
uses the fallback language. The attribute "xml:lang" is never evaluated. -->
<html lang="foo" xml:lang="sv">

Checking the request locale

If the document provides no indication of the visitor’s locale, Unblu analyses the HTTP request headers. How it does so depends on the configuration you have put in place:

If com.unblu.text.useLanguageCookie is true, Unblu will use the locale defined in the cookie x-unblu-locale.
If the first check fails, and com.unblu.text.useBrowserLanguage is true, Unblu will use the browser language as defined in the Accept-Language request header. For example, the following request header would cause Unblu to set the locale to "Swedish":
```
Accept-Language: sv
```

Determining the locale without the Unblu snippet

If you decided not to integrate Unblu into your website with the Unblu snippet, you should set the locale when you configure the Unblu JS API. See the section on setting the locale with the JS API above.

For more information, see the Unblu Visitor JS API documentation.

A number of browsers block third-party cookies. As a result, you can’t simply set the visitor’s locale with a cookie in a cross-origin installation. Fortunately, there’s a way to work around this restriction: the Unblu servlet /unblu/language.

The servlet sets (or resets) the x-unblu-locale cookie for the visitor and redirects them to another URL. To do so, you must call the servlet with three URL parameters:

action, which must be one set or reset
lang, the language to set in the x-unblu-locale cookie
redirect, the URL that visitors should be redirected to

Listing 2. Example URL with parameters for setting the locale to German with a cookie in a cross-origin setup

/unblu/language?action="set"&lang="de"&redirect="https://yourcompany.com/unblu/"

This method of setting the locale also works if you are using the Unblu Cloud.

The other methods of setting the locale also work in cross-origin setups.