How a user’s locale is chosen

This brief section explains which i18n bundle is delivered to the browser.

When you include <@i18n.bundle@/> in your webpage, a request is sent to the server, to load the map of i18n tokens for the users locale.

Detecting a Locale

There are two ways that the locale can be chosen by the client:

  1. Cookie - If a cookie is detected with the value CAPLIN.LOCALE, it will pick that locale

  2. Browser locale headers - If no cookie value is detected, then the i18n bundler will pick the locale from the browser headers

Delivering a locale

The i18n bundler now looks for resource files, and delivers the most specific translations. Let’s run through an example:

Files

Let’s say that two locales (en and en_GB), are defined in $ASPECT_ROOT/app.conf, like so:

locales: en, en_GB

The en.properties file has the following content:

greeting="Hi!"
goodbye="Bye!"

Whilst the en_GB.properties has contains this:

greeting="Hello!"

Responses

If the browser requests en_GB, it gets this response, with the greeting from en_GB.properties overriding the default setting for en:

greeting="Hello!"
goodbye="Bye!"

On the other hand, if the browser requests en_US, it receives its entire response from the en.properties file, like so:

greeting="Hi!"
goodbye="Bye!"

This is because of from the request, en is the most specific locale that has been defined.

If the browser requests fr_FR it will receive:

greeting="Hi!"
goodbye="Bye!"

In this case, it’s because the request did not match any of the available properties files, so by default, the bundler uses the first locale in app.conf.