Professional Documents
Culture Documents
Introduction
Overview
language capabilities in both the user and application environments (business solutions).
Application screens can dynamically integrate the language preferences of both the user
and the customer, which is useful in customer service settings. Thus, multi-lingual users
that handle calls from multi-lingual customers can optionally see structural information in
their preferred language, while seeing scripts, descriptions, and correspondence as the
customer would see them. The rules architecture seamlessly integrates elements based
Although the core development environment is based in English, beginning in Version 4.2
Service Pack 5, PegaRULES has the ability to present users with forms and rule
overridden with the user’s choice of language in the following key areas:
Note that only the user interface functionality is being localized. The PegaRULES
endeavor to comply with all the SmartBuild practices and guard rails; this will
make localization and maintenance of the application much easier and more
efficient.
handling, importing, and exporting character sets beyond the Roman character set
(ASCII).
when writing output or HTTP on the file system. UTF-16 is a two-byte form of Unicode.
Process Commander runs in the Java Virtual Machine (JVM); by default, the JVM strings
are UTF-16.
Process Commander uses standard JDBC interfaces to integrate with the PegaRULES
database. As long as the database supports Unicode, the JDBC drivers (which run as
part of the JVM) should take care of the data transformation from UTF-16 to whatever data
type the database expects. Thus, Process Commander supports whatever the customer
database and their chosen JDBC drivers support, including both UTF-8 and UTF-16.
Important: For most non-localized Release 4.2 installations using Microsoft SQL Server,
the following setting is included, either in the JDBC URL or the DataSource setting:
the existing database does not have Unicode on all the columns, the database
must be changed. For some databases, this may require reinstalling the
database software (and then reinstalling any other software - such as application
Options.
NOTE: If Cancel is clicked when prompted for the CD, the installed fonts are not removed
and the web page may now display correctly. If Cancel is clicked, the language selected
is not completely installed, and the checkbox is removed from the Language Settings for
If the additional files are installed from the CD, other languages may now display correctly
also, since some fonts are shared across multiple scripts. (For example, after clicking
Cancel during the install for Traditional Chinese, a font suitable for it was available, but no
support for Japanese. After completing the full installation for Traditional Chinese, a font
that was suitable for Japanese was also present – and some, but not all, glyphs in
Simplified Chinese.)
3. Font support may be added for multiple languages by installing Microsoft Office
International Support (and in particular the so-called “Universal Font” Arial Unicode MS).
Anyone who wishes to write an application in a language other than English, or localize an
existing English application into another language, would begin by obtaining the
appropriate Language Pack, and then developing/translating their own application rules
Thus, for the standard PegaRULES RuleSets, the following is an example of the list of the
AcmeProducts_es:03-02
AcmeRulePro_es:04-01
to see if a
database. If it is, the existing localized variants of that RuleSet are inserted automatically
before the base RuleSet. When the user’s Organization, Division, or Access Group
RuleSets are added, the localization RuleSets are included automatically as well. When
the RuleSets are fully assembled, each requestor will have two RuleSet Lists associated
with it: the basic RuleSet List (which appears in the user’s Profile), and the localized
RuleSet List, which is associated with the requestor itself on the Clipboard.
• When changing the Locale, it is not possible to switch out individual RuleSets –
• The base RuleSets for PegaRULES Process Commander are in US English (by
multilingual application for locales other than en_US, it is suggested that the base
application RuleSets also be in US English, even though that may not be the
preferred language for the customer. Since the customer will be building several
across the product. For example, if a French company (“La Paniere”) creates an
application, their base RuleSet would be in English (PaniereCo: 01-01), and their
• The system tests each possible localization against the Rule-RuleSet-Name (for
the base RuleSet) only – not against any Rule-RuleSet-Versions. Once it has
determined the appropriate name for the RuleSet (by taking the existing base
RuleSet and adding the appropriate localization designation), it will search for the
RuleSet and Version which match the existing base RuleSet and Version. For
02”), the system will look for the localized version of that RuleSet
cannot.
that RuleSet and start the version numbering again at 01-01 (since it’s a new
• If a user changes the locale (either by changing it in the browser or by using the
Set Locale tool), the system will automatically take the original base list of Rules
(that is displayed in the Profile), and re-localize this list based on the new locale
information.
French (in France) or French Canadian, they would get a list of 18 RuleSets. If
they were to switch to Spanish, they would only receive 14 RuleSets, as there are
These localization RuleSets should be added into the developers’ Access Group, in the
order they appear on the clipboard. Thus, the most specific localization RuleSets should
be listed before the less specific localized RuleSets, which in turn should be listed before
26 CONFIDENTIAL
Localizing the user experience for PegaRULES Process Commander can be divided into
along with the standard manager’s reports. Note that the developer tools (such as “Where
The Work Item (or items) are the focus of applications written in Process Commander, and
as such, are custom to each application. These must be localized by the developer, using
Work-
pyCountry
Data-Party
pyCountryCode
@baseclass
Work-
(flows)
pyInstructions
@baseclass
pyMessageLabel
@baseclass
pyStatusWork
Work-
only)
pyStatusLabel
@baseclass
IMPORTANT: For all rules which have autogenerated HTML, it is required to define new
• harnesses
• sections
• flow actions
The localization functionality for these rules will look for the appropriate Field Value for a
label in a specific “group;” if the Field Value has been defined in a different group, then the
system will not find it and will not localize that label.
In the sections below which give details about these rules, the label fields on the rule and
As stated earlier, the first parameter for this Field Value is a reference to the property
Backward compatibility
applications written before the release of Service Pack 5, this functionality will still be
supported.
• If the Category field is blank, then the data in the Message field is parsed as a
Rule-Message instance.
• If the Category field contains data, then the data in the Message field is parsed
as a Rule-Obj-FieldValue instance.
History/Audit Fields
The functionality of storing and displaying History or Audit data in general is different than
other localization features, and should be treated separately. This functionality includes:
For most labels, the localization lookup is immediate: the user completes the action of
Opening a New Item, for example, and the system does the localization lookup and
displays the new work item in the user’s chosen language. History messages, however,
The History message may be created when a user completes an action – transferring a
work item, resolving it, etc. – but it will not be viewed until the user actually clicks on the
pyConfirmationNote
Instructions
@baseclass
pyInstructions
StatusWork
Work-
pyStatusWork
StatusAssign
@baseclass
pyStatusLabel
The flow action rules are all displayed in the Take Action drop-down menu, where the
user chooses an action for the work item. Some of these may be custom-created by the
developer, or the developer may use the standard ones provided with Process
Commander.
HTML Tab
The developer must begin by ascertaining that localization is possible for a particular flow
existing flow actions; in order to enable localization, the developer should start with a flow
There are a number of settings on the HTML tab which affect localization.
Auto Generated
HTML
checked (enabled)
must be auto-generated. If
automatically uncheck.
described above. The HTML tab should have the following settings:
As with flow actions, the Layout tab should be displayed in “smart frames,” and each
user-visible label should have a corresponding Field Value created in order to localize its
text.
For the fields on a section, Field Values should be defined on the following “grouping
properties.”
Label type
buttons, URLs
@baseclass
pyButtonLabel
Title
header, tabs
@baseclass
pyCaption
Tooltips
@baseclass
pyActionPrompt
Value
labels
@baseclass
pyCaption
Creating Reports
In Service Pack 5, many of the standard Summary View and List View rules have been
localized. Their shared localization functionality is described here; for functionality specific
to the rule type, please refer to the Summary View or List View sections below.
Like the work item Rules, localization begins for both View rules with a Localize?
checkbox on the HTML tab. This box must be checked for localization to be enabled for
the reports.
Unlike harnesses and sections, it is not possible to change the HTML in this tab – it is
generated HTML only. Thus, the Auto Generate HTML checkbox (and related
checkboxes, like Omit extra spaces) is not necessary and does not display.
tab.
abled, these
label fields will automatically search for Field Value references. If an appropriate Field
Value is not found, then the system will return the text which is in the label field.
CONFIDENTIAL 61 Creating the Application
On both the Content and the Drill Down tabs, the labels are in Caption fields.
The Organize tab, on the other hand, displays the captions for buttons or links on the
report:
Thus, Field Values which are defined for these labels should be in the following groups:
Label type
Usage
Field Value
Applies To class
property)
Caption (Content or
report labels
@baseclass
pyCaption
Caption (Organize
tab)
button or link
captions
@baseclass
pyButtonLabel
Full Description
report title
@baseclass
pyMessageLabel
List Views
List View rules have different labels than the Summary Views. On the Display Fields tab,
the Field Labels contain the column headings for the list.
There are a number of Caption fields on the Content tab, but none of these are localized,
as the user doesn’t see them.
The Organize tab also contains Caption fields; as with the Summary View rule, these are
Thus, Field Values which are defined for these labels should be in the following groups:
Label type
Usage
Field Value
Applies To class
property)
Field Label (Display
Fields tab)
Column headings
@baseclass
pyCaption
Caption (Organize
tab)
button or link
captions
@baseclass
pyButtonLabel
Full Description
report title
@baseclass
pyMessageLabel
Correspondence
• Rule-Obj-Corr
• Rule-Corr-Fragment
Localizing correspondence is a completely different process than localizing the work item
that a user sees. The work item is localized based on the user’s locale, and displays
according to the person who is working on the item. However, there are two people
involved in correspondence - the sender and the recipient. Therefore, using Field Values
to localize the item in the language of the user who is creating the item may not be correct,
as the correspondence really needs to be in the language of the person who is receiving it,
language correspondence rule is written, that rule should be copied, and a circumstanced
version of that rule should be created, based on the property which indicates in which
This version of the rule has been circumstanced in French, and the text translated:
Application
If a developer does choose to use custom code, there are special localization features
which should be employed, to make sure that this custom code is still localizable.
HTML rules where the code is not automatically generated, but the HTML is written
• Rule-HTML-Fragment
• Rule-HTML-Property
These rules may be generated either to use industry-standard JSP tags (recommended)
As with the other rule localization, where labels are needed, these references must not
contain hard-coded English, but must point to Field Values, where the Localized Label
field provides a translation into the required language. Different code is used depending
upon whether the HTML rule is generated to use JSP or custom Pega (HTML) tags.
Important: As with the generated HTML rules (described in the previous section), if there
are no existing Field Values for the reference, the system will return the text label (“Expand
all”).
HTML rule.
In this rule, terms such as “Attach File” and “Upload in Progress . . .” are hard-coded into
the HTML display. In order to localize this rule, these labels must be changed to Field
Value references.
All localized values for the lookup tags are stored as Rule-Obj-FieldValue instances. As
• Field Name (pyFieldName) – the name of the property the Field Value is defined
• Field Value (pyFieldValue) – the actual key name of the Field Value
There is also another field on the rule, .pyLocalizedValue, which is the value in the
Localized Label field which holds the translation of the Short Description.
In order for a lookup tag to find the appropriate instance in the database to retrieve, it will
There are two different ways that lookup can be enabled for localization. For each of
these, the syntax does not specify the class name of the item; this syntax signals the
Example:
Attributes
property
required
Notes
When this syntax is used to look up Field Values, there are a number of assumptions
• Key – “Defined on” class name: the class of the primary page present at runtime
• Key – Field Name: the name of the specified property (the grouping property:
“.pyButtonLabel”)
In this example, the system will use the grouping property name “.pyButtonLabel” to look
up a value. It will look up the Rule-Obj-FieldValue instance with the following information:
• Class Name (pyClassName) – the class of the primary page (in most instances,
the system will end up finding the Field Values defined on @baseclass)
(“RemoveFromFolder”)
The system would look at the current value of .pyButtonLabel, and then return the rule-
resolved value stored in the .pyLocalizedValue. (This could be the German, French, or
Important: For this reference to work correctly, the developer must be sure that there will
be a current value of the referenced Field Value on the clipboard at execution time.
Syntax
Example:
Attributes
property
required
the Field Name – the name of the “grouping” property of the Field
value
required
formatOutput
optional
Notes
If the developer wishes to use a specific Field Value and look up its localized value, then
This syntax requires that a page be specified as part of the property reference, so the
system may determine the class name from that page. Since the “grouping property” is
generally just used to group the field values (as opposed to being an actual property), it
may not be on an actual page in the clipboard at the time it is referenced. A page needs
to be referenced which will always be on the clipboard, so the system may then search
the class hierarchy and find the Field Values in @baseclass. Since the requestor page is
always present for a work item, that page is frequently used as a “placeholder” page for
Additional References
If the Field Values have parameter or property references defined, these references must
have corresponding data in the Field Value call. Thus, if the Field Value definition for
then the lookup reference would have to include a parameter for that Field Value:
Application\tparam.StartMortgage”/>
As with the Field Value references in activity methods, the syntax for the parameter or
getLocalizedTextForString
In addition to using JSP tags, there is a Java method which is also available for localizing
into the HTML rule, with a linked Rule-Obj-FieldValue instance which is localizable.
string.
string=tools.getLocalizedTextForString(“page.property”, “Value”)
As explained in the previous section, the Rule-Obj-FieldValue class contains three key
properties:
• Class Name
• Field Name
• Field Value
There is also another field on the rule, .pyLocalizedValue, which is the value in the
Localized Label field which holds the translation of the Short Description.
The first parameter, Ref, is the reference to the page and property name for the text string
to be localized. The system derives the Class Name from the specified page & property
reference, and then also uses this property reference as the Field Name. Thus, this
this is a named page which will always be present on the clipboard, but other pages
The second parameter, String, is the actual Field Value (the key name for the Rule-Obj-
FieldValue instance):
• Export To Excel
• Refresh List
etc.
Once the Field Values have been created, they may be referenced by
The first decision the developer must make when determining how to reference
going to be referenced several times in the rule, then it is more efficient to cache that
information locally and retrieve it from the cache, rather than going out to the database to
retrieve the value each time. If there is only going to be one reference to the text in the
Another decision for the developer is whether to use Java or HTML code to refer to the
text string. If the code in the rule is mostly Java, then that may be the most efficient way to
reference the string; on the other hand, if the code is mostly HTML, it is also possible to
set up the reference so that switching into Java code in the middle of the HTML is not
necessary.
Commander rules. Developers would not be changing these particular rules, but should
look at these examples to determine how best to change rules in their own application, or
This code does not include caching, as there is only one reference to the string. This
<%
String EXPANDTEXT =
tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand");
String CONTRACTTEXT =
tools.getLocalizedTextForString("pxRequestor.pyCaption","Contract");
// Get the list size, small or full, stored on the Work pyPortalPage
if (pgDataPortal != null) {
ClipboardProperty cpPortalPages = pgDataPortal.getProperty("pyPortalPages");
if (pgPortalPage.getString("pyCaption").equalsIgnoreCase("Work")) {
strWorkListSize =
pgPortalPage.getString(".pyPageParams.pyWorkListSize");
break;
+ "?pyActivity=Data-Gadget.ShowWorkView&ViewClass=Assign-
Worklist&ViewPurpose=&ViewOwner=ALL&pyAction=Refresh&showHeader=false&UserID="
+ userId + "&ViewHeader=false&glimpseMode=Scripts&workListSize=" +
strWorkListSize;
%>
In the above example, two strings were being localized: “Expand” and “Contract”. A local
string variable was defined for each of these (EXPANDTEXT, CONTRACTTEXT), and set
equal to the Rule-Obj-FieldValue instances for those values in the pyCaption grouping
are the HTML references stating that the data enclosed between these symbols is Java
code; the “<” symbol means that this rule has been generated for JSP tags.
This code includes caching. This HTML rule is also generated for JSP.
<%
tools.putSaveValue("CAPTION-expand",
tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand"));
tools.appendString("<a href=\"javascript:executeList(");
tools.appendString("10,10,80,80,");
tools.appendString("</td></tr>");
code uses putSaveValue. The local variable being used is “CAPTION-expand”; the
capital letters in the “grouping” allow the reference to be easily found in the code. Like the
first example, this code also points to the Expand Rule-Obj-FieldValue instance.
<HTML>
<HEAD>
{JAVA}
// no assigments message
saveValueSet("MESSAGE-noAssignmentsFound",
tools.getLocalizedTextForString("pxRequestor.pyMessageLabel","NoAssignmentsFound"));
saveValueSet("CAPTION-of",
tools.getLocalizedTextForString("pxRequestor.pyCaption","Of"));
saveValueSet("CAPTION-expand",
tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand"));
{/JAVA}
<table width="100%">
<tr>
<td style="width:100%;text-align:center">
<a href='javascript:showUserWorkList("{pxRequestor.pyUserIdentifier}")' >10
</tr>
<tr>
<td style="width:100%;text-align:center">
<a href='javascript:showUserWorkList("{pxRequestor.pyUserIdentifier}")'
{$save(CAPTION-expand)}<a></td>
</tr>
{else}
<tr>
<td style="width:100%;text-align:center">{$save(MESSAGE-
noAssignmentsFound)}</td>
</tr>
In this example, the getLocalizedTextForString references are saved into a cache using
saveValueSet in a Java section at the top of the code. However, in the code itself, the
reference to the string uses $SAVE. This designation can be used when writing directly in
HTML, so the developer doesn’t have to drop into Java code (to use the
tools.getSaveValue method).
If the rule has been generated for JSP tags, the pega:save and pega:getSaved tags can
be used. (See the JSP Stream Support tech note for further details.)
For full details on using the getLocalizedTextForString Java method, please reference the
As stated in the Field Values section of this document, there are a number of “grouping”
pyCaption, etc. These are the values which must be used when creating new localization
Field Values for harnesses, sections, and other rules where the HTML code is
automatically generated.
However, if the customer wishes to create their own custom HTML rules, it is also possible
that they could create some additional “grouping” properties to reference in these rules.
Pegasystems recommends not creating too many, or the capability to find one particular
Field Value quickly will be lost. (Creating 100 groups for 100 Field Values will not aid a
There are three steps to creating and using a new Field Value group:
The first step in creating a new Field Value group is to create the grouping property. This
property should be defined on a class which is at the most general level possible in the
hierarchy, in order to allow the Field Values in this group to be used by the widest possible
number of classes (i.e., to promote reuse). Most of the grouping properties shipped with
Once the new grouping property is created, define the appropriate Field Values on this
property. For example, the customer might create a new grouping property called
After the Field Values have been defined on the new grouping property, they can be
referenced in custom HTML rules. These references could be either a lookup reference,
or a getLocalizedTextForString reference.
lookup example
In an HTML rule which is generated for JSP, the pega:lookup syntax could be used:
getLocalizedTextForString example
This new Field Value reference could also be used with getLocalizedTextForString:
tools.putSaveValue("PRODUCTS-monitors",
tools.getLocalizedTextForString("pxRequestor.Products","Computer Monitor"));
Properties can have different types in the PegaRULES system. Localizing requires
Number-Formatted Properties
• date
• time of day
• Date/Time
• integer
• number
• decimal
• double
Clicking the Demo button in the Set Locale tool displays all property types that will be
Once the locale has been changed (either through the browser or by using the Set Locale
tool), all properties of the above types should automatically display data in the correct
format for the locale when either the default Rule-HTML-Property instance or no Rule-
HTML-Property instance is associated with the property (in the HTML Property field).
For example, a DateTime property with no HTML Property specified would display in the
available:
DateTime-Full
DateTime-Full-i18n
DateTime-Long
DateTime-Long – i18n
DateTime-Medium
DateTime-Short
DateTime-Short – i18n
Examples of these Short, Medium, Long, and Full DateTime formats are displayed in the
for the default locale, but the Rule-HTML-Property instance will accept the specific locale
parameter and use that formatting for a different locale passed in as a parameter. If the
“base” (non-i18n) version of the Rule-HTML-Property instance is used, then both the
default locale values and the “specified” locale values would appear in the format of the
default locale.
Thus:
• When the system will only use locale information from the browser (the “default”
• When there will be another locale specified in processing, but the default locale
used.
82 CONFIDENTIAL Localizing Properties
Text Properties
Properties may be defined so that a drop-down list of choices is displayed to the user for
setting a property value. When creating the property, the developer should choose a
Table Edit type on the Table Edit tab to populate this list:
the Short Description of the Field Value in the base RuleSet, the system will generate a
localized drop-down box by displaying the values from the Localized Label fields of the