A locale specifies what country specific data will be used by an Application, for text translation, Date and Time formats, number separators, etc.
XPages calculates the locale based on the browser locale. <$DXContinueReading$> The locale also depends on whether the localization options are enabled, and if so, on the list of supported locales for this application.
Time zones are no longer discussed here; that section has been moved to the article
Time Zones in XPages
The sections in this document are
Locale usage
The context locale used in an XPages application is calculated based on the browser locale. The context locale is used for:
- Choosing Translated Server Strings
Some translations are provided by the Domino Server Language Pack installers. For example, the column headers in the File Download control are translated by the server, so the user does not need to translate them in every application that uses the control. Similarly if you choose to make a field required and do not provide your own error message, a translated message is provided by the server. The context locale is used to determine which translation of the message is displayed.
- Choosing Translated Application Strings
When building Applications you can provide translations of the text used in your XPages and Custom Controls. The context locale is used to determine which application translations are used.
- Formatting Locale-dependant Data in converters
Some data is displayed in different formats in different countries, such as dates, numbers and currency values. Locale-aware converters are used to display such data.
- Choosing Dojo Translated Strings
Some controls use the Dojo Toolkit JavaScript library, which provides its own translated strings. For example, the tool tips for the buttons in the Rich Text control are supplied by the Dojo translation mechanism. The Dojo translations are always included in the server, even when the Language Packs are not installed. The Dojo locale is usually the same as the context locale, except for the deprecated locales listed in the last section below.
- Computing the page dir and lang values.
In the All Properties tab for an XPage you can set the properties "dir" and "lang". If not set there, the properties are computed based on the context locale. The "lang" is the language used in translated text in the page. The "dir" is the direction of the page text; in Arabic and some other languages, text is read from right to left, so the dir is set to "rtl". Use context.isDirectionRtl() to access that value programmatically.
- Loading a Bundle Resource.
Resource bundles are used to translate text in your application's Server JavaScript scripts. See the document "XPages: JavaScript Internationalization" for information on bundle resources.
- User scripts that compare strings, convert to lower/upper case etc.
The I18n library contains a set of functions that feature a Locale argument. For example, changing the case of accented characters behaves differently per locale, so there is a method I18n.toLowerCase(string, Locale). By default, those functions use the server locale, but the context locale should usually be passed as the locale argument.
Converter locales
Converters are used on an Edit Box or Computed Field to convert a data object like a date or number into a string to be displayed to a user. They are also used to convert a string entered by a user back to a date or number object. Converters need locales because the formats used to display dates and numbers vary from country to country. For example, the short date format used in the United States is 12/25/2008 but the format used in the United Kingdom is 25/12/2008. Hence converters use different locales even when language is the same.
To configure a converter on an Edit Box, in the Properties Data tab, choose an option in the "Display Type" list on the right.
Converters normally use the context locale, but it is possible to configure the locale for an individual converter if required. You can set or compute the converter locale in the All Properties tab of the Properties view. The "converter" property will contain an "xp:convertDateTime" or "xp:convertNumber" value which contains a "locale" property. If you click into the locale property, you can choose the locale from the drop down list or click the blue diamond icon to compute the locale.
To get the locale in server scripts.
To access the locale programmatically use
context.getLocale() : Locale
That context locale is used by the XPages runtime. You should usually use that locale in your own scripts.
There are some other locales available.
- I18n.getServerLocale(): Locale
The server locale is available through the I18n library. It corresponds to the operating system locale of the server. It is not related to the user's browser locale.
- view.getLocale() : Locale
The current locale from the context is used when loading the view (JSF page), to choose localized strings etc. The view locale cannot be changed after the view is loaded.
- facesContext.getExternalContext().getRequestLocale()
is the first locale configured in the user's web browser. The context locale is often the same as browser locale, but not always. See the "How the locale is calculated" below for details.
If the context locale is set explicitly in code, it persists across requests for the remainder of the current session.
After setting the locale, it is important to either reload the current XPage by calling context.reloadPage(), or redirect to an XPage, so that the localized strings are re-read in the new locale.
To set the locale, if only setting a language use
context.setLocaleString("fr");
If setting both language and country or region, use
context.setLocale(new Locale("fr", "BE"));
which sets the language French and country Belgium.
To clear the locale so it re-calculates it again, do
context.setLocale( null );
[In 8.5.1 and later, you can call context.setLocaleString("fr_BE") and it will parse the string, but in the 8.5 release that does not work so you should use the setLocale method.]
For example, this page allows you to click buttons to change the locale. The file download control is provided so you can see the localized text in its column headers. Note, you need the French language pack installed to see this work.
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:label value="The current locale is:" id="label1"
for="computedField1"></xp:label> 
<xp:text escape="true" id="computedField1"
value="#{javascript:context.getLocale()}"></xp:text>
<xp:br></xp:br>
<xp:button value="to English" id="button2">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action><![CDATA[#{javascript:
context.setLocaleString('en');
context.reloadPage(); // this is important
}]]></xp:this.action>
</xp:eventHandler>
</xp:button>
<xp:button value="to French(Belgium)" id="button1">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action><![CDATA[#{javascript:
context.setLocale(new Locale("fr", "BE"));
context.reloadPage(); // this is important
}]]></xp:this.action>
</xp:eventHandler>
</xp:button>
<xp:fileDownload rows="30" id="fileDownload1"
displayLastModified="false"></xp:fileDownload>
</xp:view>
How the locale is calculated
If the locale was programmatically set in a previous XPage (context.setLocale()) during this session, that locale is used.
If the localization options are not set, and the user has a browser locale, the first browser locale is used.
If the first browser locale is a Norwegian language, it is handled specially (see the section on Norwegian).
The first browser locale is compared to the list of supported locales to find the best match. If there is some match, the best match locale is used.
[To enable localization and configure supported locales in the Application Properties, see "
XPages: How to use the localization options".]
If the first browser locale does not match any of the supported locales, the 2nd browser locale is compared to the supported locales list, and so on for all the browser locales.
If the none of the browser locales match any of the supported locales, then the configured default locale is used.
If there are no browser locales (unlikely since all browsers are installed with at least one) and no default locale, the server locale is used.
Norwegian and the deprecated locale codes
Some of the locale codes for languages have been deprecated. As a general rule, core XPages uses the old code, but the Dojo Toolkit uses the new code. The exception is Norwegian, which is handled specially.
The Dojo Toolkit is a JavaScript library used by XPages for some controls. It contains some translated strings, such as the tool tips for the buttons in the Rich Text control. When a Dojo control is present, the Dojo locale is output to the HTML source by the XPage. That Dojo locale will differ from the XPage locale for the deprecated languages above, and for the other Norwegian languages.
The old code for Norwegian was "no", but actually there are 2 different Norwegian languages, so that old code was deprecated and 2 new codes were created. The most common Norwegian language is Norwegian (Bokmål), which now has the locale code "nb". Text that was previously translated to the "no" language would actually have been translated to Norwegian (Bokmål), so it is often possible to consider "nb" as the new name for "no". The other Norwegian language is Norwegian (Nynorsk), which now has the locale code "nn".
Some browsers only use the new codes ("nn" and "nb"), some only use the old code "no", and others allow all the codes in the browser locales list.
Different Norwegian languages will be used in the different locale usages described above. This table shows the locale code actually used for each locale usage and for each browser request language, depending on whether localization is enabled. [To enable localization, see the Application Properties setting in "
XPages: How to use the localization options"]
|
|
|
| no | nb | nn |
With localization disabled
|
|
| no | nb | nn |
|
| no | no | no |
|
| untranslated | untranslated | untranslated |
|
| no | no | no |
|
| nb | nb | nb |
With localization enabled
|
|
| no | nb, else no | no |
|
| no | no | no |
|
| no | nb, else no | no |
|
| no | no | no |
|
| nb | nb | nb |
The XPages translated server strings are only translated to "no", so if a browser request comes in for the "nb" or "nn" languages, the "no" strings are served up. When localization is disabled, the Application translation is disabled. The Application strings will be either "no" or "nb", depending on the language chosen in the Application Properties in Domino Designer. If localization is enabled, and there is a request for "nb" strings, it will check for "nb" strings and if they are not present, it will serve the "no" strings. The Dojo strings in the 8.5 release were provided in the language "no", but in 8.5.1 and later Dojo uses the language "nb". With localization enabled, the context locale is never "nn", because the localization setting restricts the context locales to only those in the Application Properties supported locales list, and "nn" is not an option in Application Properties.
All this assumes that the server language packs are installed, or else the server itself will have no translations, though translations in an application will still be available. Dojo does have built-in date formatting for the "nn" and "nb" languages, but that date formatting is not used by XPages, so the languages "nn" and "nb" are never output as the Dojo locale. If you are translating to a Norwegian language and you have any scripts that use or calculate the locale, then you may need to add your own special handling for Norwegian.