NexJ CRM provides the following internationalization and localization capabilities:

• NexJ CRM supports English, and was built to work with Unicode for supporting other languages.
• Specific formatting is supported for dates, currency, and numbers.
• Multi-language support is built into the business model for code values.
• Display language is selectable at runtime.

Overview

To support a new language you need to add resources with a new language tag. The language tags are based on rfc 4646. More information can be found at https://en.wikipedia.org/wiki/IETF_language_tag. Examples of language tags are "en" for English, en-CA for Canadian English, es for Spanish, ...

At a high-level, for each supported major language, a new entry is made in the SupportedLocalEnum enumeration. 

New string files are created that end in <languageTag>.strings.  For more information on strings, see For a full picture also read https://confluence.nexj.com/display/PUBDEV9/Strings. These can be populated using the string import/export tool in NexJ Studio.  

A new <languageTag>.locale file is created in the /meta/locales folder. Additionally, a new locale/string file is created in /mod/i18n/<languageTag>.js.  More information on this may be found at .AFL Developer Guide v9.2.

Configuring supported client locales

To configure supported client regional locales, you must modify the corresponding .locale file by adding the ids.format.regionalLocale property, if it does not already exist. The locale files can be found in the Resources > Locales tab in NexJ Studio. They can also be found in the meta/locales directory in the project folder. For example, finance/meta/locales.

The value for this property should be a valid combination of a language code and a region code separated by a hyphen, for example, en-CA (Canadian English).

The format and capitalization for the value of this property must follow a specific standard. The full property and value added to a .locale file should look similar to: 
ids.format.regionalLocale=en-CA

Each .locale file can have its own value for this property. For example, the property mentioned above can be added to the en.locale file, and the following property can be added to the fr.locale file:
ids.format.regionalLocale=fr-CA

By adding this property to the .locale files, the values attached to them build the supported client locales accepted by the application.

Setting locale

You can change locale via URL or via browser language. 

To change locale via URL, you must add the l parameter to the URL and the value specified should be an exact match for the value of the ids.format.regionalLocale property in the .locale file. For example, if an application's URL is http://www.nexj.com/nexj/ui/portal, then use the following URL to indicate that Canadian English should be used http://www.nexj.com/nexj/ui/portal?l=en-CA. If there is already an appended URL query parameter, add &l=en-CA to the URL instead.

To change the locale to match the browser, use the browser settings to change the browser language.

Configuring a project default locale

You can configure the default locale for the project. It will be used if the incoming locale (either entered as the URL or the current user’s browser locale) is not supported by the application. To set a desired project default locale, modify the FALLBACK_LOCALE attribute in the User class (User.meta).

Locale selection precedence

Because there are multiple different ways to set locale, which can have varying values, for example, URL, browser, project default, and so on, there is a priority system in place to determine which value has precedence.

The priority, from highest to lowest, is:

• URL
• User model (locale attribute in User.meta)
• browser locale
• project default
• en-CA

A locale specified in the URL has the highest priority. As long as the locale value in the URL is supported, that client locale is used.

If there is no locale set in the URL, the user locale value is checked. If supported, the user locale value is used. Otherwise, the browser locale is checked. If the browser locale is supported, it is used. If the browser locale is not supported, the project default locale is used.

If the project default locale that has been configured is not a valid supported client regional locale (by misconfiguration, for example), the application defaults to en-CA.

Using a flag to determine User model precedence

You can use the ignoreUserLocale flag from the framework to determine when the User#locale value should take precedence or not. 

When the value for the flag is false, which is the default value, the User#locale is used. If the value is true, the User model value may not match the locale value that was set in the URL, and the client locale should be used instead. In this case, the returned value is the existing clientLocale value, as tracked by the framework.

The following example shows the usage of the flag in finance. It is taken from the locale attribute for User.meta in finance. The methods, which get and set the ignoreUserLocale flag, exist for the nexj.core.runtime.InvocationContext class, and therefore a nexj.core.runtime.InvocationContext instance is needed to call these methods.

(cond
   //If the flag is TRUE (locale set from URL), then we can’t use the User model value, therefore, use the client locale value tracked by the framework (InvocationContext#getClientLocale).
   (((invocation-context)'ignoreUserLocale) ((invocation-context)'clientLocale))
   //ELSE the flag is FALSE (locale not set in URL), continue to User model logic
   (else
      … 
   //Retrieve user model locale/validate/use fallback/etc.

Enabling en_US language support

By default, the en locale uses the Canadian format for dates (day/month/year). If you want to be able to display dates in the US format (month/day/year), you must enable the en_US locale.

To enable the en_US locale and to provide the ability for users to select either the en_US or the en_CA locale for English, do the following:

1. In NexJ Studio, in the Business Model layer, open the Enumerations tab.
2. Open the SupportedLocaleEnum enumeration.
   • If SupportedLocaleEnum is not already customized, right-click on SupportedLocaleEnum and select Customize Using > Base.

3. In the Values section, add a new value and specify the following settings:

   Field name	Setting
   Name	en_US
   Value	en_US
   Has Behavior	true (checkbox selected)
   Display Updatable	true (checkbox selected)

4. Select the new value. In the Value Captions section for en_US, add a new preferred value caption for each supported locale. For example, if you have en, fr, and en_US locales, specify the following settings: 

   Field name	Setting for en locale	Setting for fr locale	Setting for en_US locale
   Locale	en	fr	en_US
   Caption	English (United States)	anglais (États Unis)	English (United States)
   Short Caption	en_US	en_US	en_US

   This will be reflected in the source code in the following:

   <Value hasBehavior="true" name="en_US" value="en_US">
      <Locales>
         <Locale caption="English (United States)" name="en" shortCaption="en_US"/>
         <Locale caption="English (United States)" name="en_US" shortCaption="en_US"/>
         <Locale caption="anglais (États Unis)" name="fr" shortCaption="en_US"/>
      </Locales>
   </Value>

5. For each of the existing supported locales, select the locale and add a new value caption entry for the new en_US locale. For example, for the fr locale, add a value caption with the following settings:

   <Locale caption="French" name="en_US" shortCaption="fr"/>

6. Add an upgrade load step to Main.upgrade and increment the version number by 1.
7. Update finance model version to match the latest Main.upgrade version.
8. Upgrade the database.

The en_US locale is now enabled and en_US data can be seeded.

To disable the en_US locale, do the following:

1. In the SupportedLocaleEnum enumeration, remove all references to the en_US locale.
2. In the Main.upgrade file, add an upgrade load step and increment the version by 1.
3. Update finance model version to match the version on the latest Main.upgrade file.
4. Upgrade the database.