You are here: Reference > Tools, accelerators, and wizards > About the Localization wizard

About the Localization wizard

Use the Localization wizard to make an application available in additional languages. The localization process overrides text in user-visible field value rules that appear in application elements such as user forms and portal displays. The wizard automates many of the steps necessary to create language-specific rulesets.

How the localization process works

The wizard begins the localization process by identifying field values and text strings used in your application ruleset user interface rules. Text includes labels, captions, ToolTips, and instructions that appear in user-facing rules, such as harness, section, flow action, message, and portal. HTML text used in HTML paragraphs, correspondence and correspondence fragment rules is also identified.
After a verification process, which ensures that the rules can be localized, the wizard collects and writes the strings to rows in an XML file. This file serves as the translator's worksheet.
The wizard creates a ZIP file called a translation package for each language you specified. The file contains an XML file and other files that help the translator successfully complete the project.
You send the package to a translator, who extracts the file and enters the translated text in the XML file. The translator zips up the set of files including the updated XML file and returns it to you.
You use the wizard to import the localized rules. To verify the translation results, you use Pega 7 Platform tools.

The Localization wizard is designed to efficiently and automatically identify relevant user interface rules. However, there may be rules that the wizard does not detect caused by unique application configurations. Complex applications will most likely require some manual translations.

Prerequisites

Before using the Localization wizard, do the following:

Test and stabilize the application user interface.
If your system was upgraded from PRPC Version 5.2 or earlier, verify that the index reference validation step was performed during the upgrade process. The list of fields for translation is derived from rule references in your application. If the references are not correct or current, it is likely that some strings are missing in the translation package.
Verify that the current system locale is the same as your base language (text in the original application). Do not run the wizard in a locale other than your base language.
If your application uses text strings in a way that does not create references (for example, uses Java to look up the localized text rather than using a pega:lookup tag), create base field values in one of your regular application rulesets so the wizard can include this text in the translation package.
Determine what language packs you have on your system. To acquire a pack, contact Pegasystems Global Services. Install language packs before you use the wizard.

Starting the Localization wizard

The Localization wizard provides three options:

To create a new translation package, selectDesigner Studio >User Interface > Localization Tools > Translate to New Language.
To list translation projects that are still in process, select Designer Studio >User Interface > Localization Tools > Translations in Progress. Select a translation project to re-enter the wizard at the step from which you exited, as indicated in the Instructions column. For more information, see Working in the wizard.
To change the locale for the current session by overriding some locale settings, select Designer Studio >User Interface > Localization Tools > Locale Settings. Review the current locale settings and complete the panel. For more information, see About the Locale Settings tool.

Click the help button on any form for help about that form.

Resuming the wizard

This wizard creates a work item with prefix pxAP-. To find open and resolved wizard work items, select Designer Studio > Application > Tools > All Wizards.

Steps in the wizard

These are the basic steps you perform in the wizard when you translate to a new language or verify a translated application.

Create and export a translation package

Step 1: Select languages — Select one or more languages to which you want to translate your application. A translation package will be exported for each of these languages.

Step 2: Select application rulesets — Select one or more unlocked application rulesets and versions you want to include in the translation package. If you have not selected any unlocked rulesets, an error will display. Select Modify Selection to return to the step and select an unlocked ruleset. Otherwise, select Proceed Anyways to export the records for translation.

Step 3: Enable Records — This step allows you to enable records for translations in unlocked ruleset versions only and is recommended for first-time translations. If you did not select an unlocked ruleset in Step 2, this option is unavailable and you can proceed to the next step.

Step 4: Export Translations — The wizard creates a ZIP translation package for each language. The package includes an XML file containing the text strings and other files the translator will need. This step allows you to save the package to a local directory so that you can send it out for translation.

Working in the wizard

Creating a wizard work item: When you select the Translate to New Language option, The Step 1: Select languages form opens and a wizard work item with the prefix of PXAP is created.

You can also create a new wizard object when you are in the Wizards in progress list (see next topic) by clicking New, which opens the Step 1 wizard form.

Opening a wizard object that is in progress: Use the Translations in Progress option to display the Wizards in progress worklist. Clicking an item opens the step at which the Localization wizard exited. The list has four columns. The fourth column (last one on the right) indicates the step at which the Localization wizard exited. When you click an item with Import status, a three-step Localization wizard opens that you use to import the translated package into your system. If you exported multiple translation packages from one wizard object, each package appears as a separate Import item in the list.

Exiting the wizard — You can exit the wizard in any step by clicking Cancel. All your entries up to that point are retained. Use the Translation in Progress option to reopen the wizard.

Localized rule types

Rule types that are localized include the following:

Rule Type	Field	Notes
Class (for work types)	Short Description	Visible on the portal
Flow action	Short Description	Basis of user selection of the flow action
Flow action Harness Section	Caption (button panel, Layout tab)	Visible on the user form
Flow action Harness Section	Value (Field panel, Layout tab)	Visible on the user form
Harness	Title (Layout panel, Layout tab)	Visible on the user form
Report definition	Report title Description Column name Caption of a filter condition Chart title Axis label of a chart	Visible on the report display
Message	Message	Localization is needed only for Rule-Message rules presented to users, such as through the Page-Set-Messages method in an activity, or a validation rule.

Localized properties

The properties listed below are included in the localization process. Some field value rules may already be defined in a language pack for the locale.

Applies To	Name	Purpose
@baseclass	pyActionPrompt	A sentence corresponding to a longer form of a pyActionLabel, as explanation that be presented as a ToolTip. For example, the pyActionLabel with English text `Add A New Party` has the Localized Label value `Ajoutez une nouvelle partie` for the Pega-ProCom_fr language pack.
@baseclass	pyButtonLabel	Generally an imperative verb that conveys a command from the user to the application, such as appears on buttons or links to be clicked. Examples of the English forms are Save, Cancel, Submit, Next, and OK. For example, the pyButtonLabel with English text `Advanced View` has the Localized Label value `Affichage Avançé` for the Pega-ProCom_fr language pack.
@baseclass	pyCaption	An imperative verb or verb plus object that is a request to the user. For example: Select a value, Click to close. May also be single word noun or noun phrase, such as Amount, Received, Due, Limit. Typically used for localized versions of field labels in sections and harnesses, and column headings in reports. For example, the pyButtonLabel with English text `Attach a File` has the Localized Label value `Joindre un Fichier` for the `Pega-ProCom_fr` language pack.
@baseclass	pyInstructions	Application-specific instructions to a user regarding a human task in a flow. These may appear on a worklist. Typically these start with an imperative verb and contain no more than six words. Examples: Verify applicant salary. Check customer credit limit. Confirm receipt of goods. Review mortgage application.
@baseclass	pyLabel	Short Descriptions for the work types (concrete class rules derived from Work-) in the application. For example, the PegaSample application includes the work type PegaSample-CustomerRequest, with Short Description `Customer Request`. The Localized Label value of the corresponding field value rule for the `Pega-ProCom_fr` language pack is `Demande du Client`.
@baseclass	pyMessageLabel	You can localize alert messages contained in JavaScripts. For examples, these field values convert messages to the user conveying errors, progress, success, or needed action. Also includes the Where-am-I? form. Examples: Enter a value; field may not be blank. Submitting... Save failed. Contact your administrator. For example, the pyMessageLabel with English text `Clear the error if you believe it has been fixed` has the Localized Label value `Dégagez l'erreur si vous croyez qu'elle a été fixée` for the `Pega-ProCom_fr` language pack.
@baseclass	pyStatusLabel	Localized versions of work item status values, such as `New`, `Open`, `Resolved`. For example, the pyStatusLabel with English text `Open` has the Localized Label value `Ouvert` for the `Pega-ProCom_fr` language pack.

Creating a language pack

To create your own language pack that includes standard Pega 7 Platform field values, do the following:

Run the Localization wizard using the Translate to New Language option. Use a ruleset that does not contain any significant user interface rules that reference field values—for example, an organization ruleset.
When you reach Step 2 in the wizard, select the second option Include all PegaRULES application rulesets. This creates a translation package that contains an XML file with all the standard Pega 7 Platform field values.
When the file is complete, import it to a top-level (organization) application ruleset so that it can be shared across business applications. Field values in language-specific rulesets Rule use normal rule resolution. Your custom language pack cannot be imported to a standard locked ruleSet such as Pega-ProCom (where Pegasystems language packs are located).