Applies to Pega Platform versions 8.1 through 8.5
Prerequisite information
Checklist for using the Pega Public API method tools. getLocalizedTextForString(String aFieldName, String aFieldValue)
Configuration errors
Prerequisite information
Field values are static text that is visible on the user forms of a Pega application. The Localization wizard sources field values automatically for translation, as described in Localized rules. See Localized field values for a list of field values that can be translated. Field values not listed cannot be translated. Some field values might already be defined in the local language pack that is installed on your system.
Field values are of key importance for the localization wizard to render auto-generated controls in the target language. Whenever you import a translation package back into the system, the system creates field values for the translated text based on the field value names. In the localization of auto-generated controls, the system uses the field value names to categorize the translated text strings by Control property name, the Localized Element, and the FieldName. See Field value mapping for auto-generated controls.
Checklist for using the Pega Public API method tools. getLocalizedTextForString(String aFieldName, String aFieldValue)
What can go wrong when using this API?
Operator locales and localized rulesets
Field value formatting of auto-generated UI controls
To find the Public API method tools. getLocalizedTextForString(String aFieldName , String aFieldValue), go to the home page of the Javadoc documentation for the PublicAPI:
From Dev Studio, click Resources > Engine API.
The Pega engine expects a well-formed primary page. That is, a ClipboardPage with the property pxObjClass populated correctly.
What can go wrong when using this API?
- aFieldName is not present in inheritance hierarchy.
- aFieldName is not present in the visible ruleset, causing the engine to look for the field value in the parent class layer present in the visible ruleset. (This is rule resolution.)
- primaryPage is classless, causing the engine to not pick the field values from the localized ruleset.
- primaryPage is an instance of an unrelated class, causing the wrong value.
- aFieldValue that starts with \t[ruleMessageName] causes the ruleMessage value to be picked from the localized or base ruleset. The rule message not being present might cause incorrect results.
Operator locales and localized rulesets
If the Operator record, the Profile tab, the Localization section, the Default locale field specifies the ISO code of the target language, the engine dynamically looks for localized field values for that language under the localized rulesets.
Example: For Operator locale de_de, the localization wizard for the language German has been run or the language pack related to German is successfully installed. During rule resolution, the engine uses the runtime ruleset list for field value resolution as follows:
- The engine checks for a field value in the localized ruleset myappRuleSet_DE:01-01.
- If the field value is found, the engine gets the value.
- If the field value is not found, the engine looks for it based on the ruleset and the inheritance hierarchy, respectively.
The following image shows an example ruleset list order for a localized operator session whose locale is de_de.
Field value formatting of auto-generated UI controls
If the translated field value has a clipboard property placeholder and a custom formatter is specified, then the engine tries to apply the formatting appropriately. If a custom formatter is not specified, then the engine fetches the formatter value specified in the rule definition of the pyLabel property of the parent Page.
Check the code of the formatter if it is not auto-generated.
If you discover discrepancies in the expected format of the localized field value, go to My Support Portal and create a support case (an Incident, INC).
Configuration errors
Configuration errors are often reported erroneously as product defects. Configuration errors are usually caused by the conditions illustrated in the following scenarios.
Scenario 1 Primary page has no class
Scenario 2 API method sanitizes special characters
Scenario 1 Primary page has no class
When the primary page has no class, a localized field value is not displayed.
In the following image, the tooltip for the Close button on a modal dialog box is localized. However, the localized tooltip value is not reflected in the UI because the primary page has no pxObjClass. See Finding the class of a rule.
Scenario 2 API method sanitizes special characters
The API method getLocalizedText(String, String ) escapes or sanitizes quotation marks and other special characters because this is required behavior of the Pega engine. The escaping or sanitizing of special characters in localized field values occurs when formatting has been applied by the formatter or control specified on the field value property because no formatter exists for the specified clipboard value.
If your requirement is to retain the original special characters for parameter values, then you need to define a custom formatter as shown in the following example.
Example
In the following example,
tools.getLocalizedText(“pyCaption” , “MyCustomFieldValue\t123’\t234”)
the FieldValue form shows the pyCaption as follows:
pyCaption ~= MyCustomFieldValue {1} this is my custom field value {2}
The Output value appears as follows:
MyCustomFieldValue 123' this is my custom field value 234.
Notice the special encoded character version of the single quotation mark (‘): '
To retain the original special characters for parameter values, you need to define a custom control with custom formatter code as follows:
- Specify the FieldValue:
MyCustomFieldValue {1 MyCustomControl} this is my custom filed value {2} - Specify the code for MyCustomControl:
<%tools.putSaveValue("result",tools.getActive().getStringValue());%>
<pega:reference name="$save(result)" mode="literal"/>
Related Content
Preparing your application for translation
Selecting application rulesets