Skip to main content
LinkedIn
Copied!

Table of Contents

Localizing field values using tools. getLocalizedTextForString(String aFieldName, String aFieldValue)

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:

  1. The engine checks for a field value in the localized ruleset myappRuleSet_DE:01-01.
  2. If the field value is found, the engine gets the value.
  3. 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.

Example of ordered ruleset lists for a localized operator
The operator Admin.local is localized for German (Current Locale de_de) with the order of rulesets and Application rulesets shown.
Example of ordered ruleset lists for a localized operator

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.

Example of class-less primary page blocking localized field value
The operator Admin.local is localized for German (Current Locale de_de) with the order of rulesets and Application rulesets shown.
Example of class-less primary page blocking localized field value

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&#39 this is my custom field value 234.

Notice the special encoded character version of the single quotation mark (‘): &#39

To retain the original special characters for parameter values, you need to define a custom control with custom formatter code as follows:

  1. Specify the FieldValue:
    MyCustomFieldValue {1 MyCustomControl} this is my custom filed value {2}
  2. Specify the code for MyCustomControl:
    <%tools.putSaveValue("result",tools.getActive().getStringValue());%>
    <pega:reference name="$save(result)" mode="literal"/>
Did you find this content helpful?

100% found this useful


Related Content

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us