Localizing field values - Documentation for BMC Helix Platform 20.08

You can localize fields of a record definition so that the end users of an application can view the application data in their locale during run time. An administrator must first add the locale information in the system and then define the fields of a record definition that are localizable.

Supported languages

BMC Helix Platform supports the following languages for localizing the fields of a record definition:

English—en
French—fr
German—de
Italian—it
Japanese—ja
Korean—ko
Portuguese (Brazil)—pt_BR
Russian—ru
Simplified Chinese—zh-CN
Spanish—es
Swedish—sv
Dutch—nl
Danish—da
Norwegian—no

You can set the required language by changing your browser locale.

To add a system locale

Log in to BMC Helix Innovation Studio and navigate to the Administration tab.
Select Configure My Server > Manage System Locales.
On the Manage System Locales page, click New.
In the Create New Locale pane, enter the locale name and the locale code.
Important
When entering locale values, ensure that you adhere to the browser's language naming convention, which is Language-Country Name. For example, en-US, en-UK, fr-FR and so on.
Click Save.

A new locale is added to the list of supported system locales.

To edit a system locale

On the Manage System Locales page, select the locale, and click Edit.
Edit the locale information as per your requirements.
Click Save.

Best practices for defining localizable fields

Consider the following recommendations when designing record definitions to include localizable fields:

When you create localizable fields in a record definition, the server does extra computation work, which slows down transactions during run time. Therefore, choose only those fields for localized values that are a must-have.
Localize fields that have prepopulated configuration data that does not change often; for example, organization name, department name, country name, and so on.
Do not localize fields that hold transactional data during run time; for example, Issue Description.
Do not localize a field that is used to store the localized configuration data; for example, a field such as Issue Type, whose values can get populated through a named list that holds different, localized issue type values.

Operations supported by a localizable field

A localizable field is of Localized Text data type and is similar to a Character field. The following table lists the operations supported by a localizable field.

To define localizable fields

Log in to BMC Helix Innovation Studio, navigate to the Workspace tab, and select the application.
Select a record definition or create a new record definition.
Click New Field to create a new field and select the data type as Localized Text.

Enter the field name and provide additional details for the field as described in the following table:

Field	Description
Name	Enter the name of the record field.
Description	Provide the description for the record field.
Required	Select to mark the field as required for the record definition.
Allow anyone to submit	Select to allow any user to submit new requests.
Change triggers audit	Select to create an audit record if there is any change in the field value.
Include value in audit	Select to copy the field value to an audit record.
(Optional) Field ID	Enter a numeric value. If the field ID is not entered, a field ID is automatically is assigned from the custom Field ID range. The Field ID range specifies the limit for values that you can assign (or are assigned automatically if you do not assign any value) to the Field ID. You can assign the value to Field ID within the Field ID range. The Field ID range for a field in a record definition is specified by BMC SaaS Operations. You cannot assign the lower limit value of the Field ID range to a field. For example, if the Field ID range is 1000:2000, the minimum value that you can assign to a Field ID is 1001.
Length	Enter the field length in characters; enter 0 for an unlimited field length. By default, field length is of 254 characters.
Default value	Click the Localize link to select a locale as the default locale. The locale values are populated from the list of supported system locales. For information about adding a system locale, see Adding a field value locale.

Click Save.

To add record instances in the localizable record definition

Select the record definition in which you want to enter values.
Click Edit Data.
In the Data Editor, click New to enter a new record.
Enter values for all the record fields.
To enter values in the localized text field:
1. Click Localize.
2. In the Localize value dialog box, enter the values against each locale that you need.
  Important
  The list of locales is populated from the list of supported system locales.
Click Save.
When a user logs in, they can see the content for that field in their locale setting. If no locale is set, the value from the default locale is shown. If the default locale is not set, a NULL value is displayed for the locale.

Example:

In this scenario, you need to add localized values to a localizable field called Department. Two system locales, German and German (Germany), are already in the system and the default locale is set to English-United States. Add localized values to the Department field as shown in the following images.

Add values to the new record and click the Localize link beside the localizable field, as shown in the following image:
Enter the localized values and click Save.
The following image shows the Localize Value dialog box:

After entering the localized values, the data editor shows the Department field values based on user's current locale.
- If your browser locale is set to de-DE German (Germany), the localized field shows values in de-DE German (Germany), as shown in the following image:
- If your browser locale is set to de-AT German (Austria) and you have not defined the de-AT German (Austria) locale for the Department field values, the data editor shows the data in the generic system locale, that is de German, as shown in the following image:
- If you have not entered the localized values for the system locale, the data editor shows the data in the default locale, that is English-United States.

Considerations when assigning a Localized Text field in a process or a rule

During assignment of a Localized Text field to another Localized Text field in a process or a rule, the assignment is successful and the entire locale map is assigned to the new field.
During assignment of a Localized Text field to a Character field, the current locale value is assigned to the Character field. If no locale is defined, the default system locale is assigned to the Character field.
During assignment of a Character field to a Localized Text field, only the current locale value is assigned to the Localized Text field. Other locale values in the map will be NULL.

Fallback mechanism for displaying localized field values

BMC Helix Platform displays localized field values to the user according to the following order of preference:

User's current locale
Generic system locale
For example, if the user's locale is de-AT German (Austria), then the fallback locale is de German.
Important
You cannot edit the value of the fallback locale.
Default locale as set in the system locale

The fallback mechanism applies when displaying values in the Record Editor, Record Grid, and View component.

Example

You have defined three locales: French, French (France), and Japanese. English US is the default locale and the user's current locale is set to French.

If the field values are provided in French, the user can see values in French.
If the field values are provided in French (France), the user can see values in French (France).
If the field values are provided in French (Belgium), the user can see values in French because French is the generic system locale.
If you have not entered an value in the Localize Value field for French locale and the user's current locale is set to French, the data editor shows the data in the default locale.