Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Localizing your application

Updated on July 13, 2023

Localizing your application helps users work in their preferred language, which improves their experience and ensures a better understanding of the product. By localizing an application, you can expand your operations to new markets regardless of language barriers.

Localization adapts your application for a specific language or region. During the localization process, the text in your application is translated into the target language, and imported back into Pega Platform. Text that you can localize includes labels, captions, tooltips, and instructions that appear in user-facing components, such as views and portals.

Localization limitations

Localization in Cosmos React applications is an expanding feature. Consequently, it includes certain use case limitations. By understanding the scope of localization support in Pega Platform version 8.7, you can plan your application better.

In Cosmos React applications, you cannot localize the following rules:

  • Decision tables and decision trees.
  • Case statuses.
  • Radio buttons and drop-down controls in a table.

In addition, localization has the following limitations:

  • If you save a view manually through Dev Studio, and not in the App Studio authoring environment, the system does not update the localization file.
  • The translation package does not automatically include the text from radio buttons and drop-down controls that use data pages. For more information about adding that text manually, see Localizing controls that rely on data pages.
  • The translation package does not automatically include the text from properties with prompt lists. For more information about adding that text manually, see Localizing properties with more than one value.
  • Deleted views are not deleted from the translation package.
  • You cannot delete localization rules.

Creating a translation package in Cosmos React

Expand the user base of your application by translating it into different languages. By creating a translation package, you bundle all the text in your application into a single JSON or Microsoft Excel file, which translators can then process more conveniently.

  1. In the navigation pane of App Studio, click SettingsLocalization.
  2. On the Localization landing page, on the Translation packs tab, click New.
    The New button on the Localization page
    The New button is located in the upper-right corner of the screen.
  3. In the New translation dialog box, click Add language.
  4. In the language list, select the language to which you want to localize the application.
  5. Optional: To overwrite a previous translation, select the Re-translate existing translations checkbox.
  6. Click Next.
    Result: The system generates a raw translation package.
  7. Click Download, and then select the format of the translation package.
  8. Click Done.
    Tip: You can download the translation package at any time, in either format, from the Language list on the Localization landing page.

Importing a translation package in Cosmos React

Create multiple language versions of your application by localizing translation packages and then importing the packages into your application. You can upload a newly translated package on the Localization landing page, which offers a convenient way to manage the language versions of your application.

In addition, you can use the Localization page to import Pega language packs, which provide a translated ruleset with values of fields that typically appear in every application, such as button labels or prompts.
Before you begin: Obtain a file with the translation or a Pega language pack. For more information, go to Pega Marketplace.
Note: Ensure that your language pack is the same version and UI type as your application. For example, Cosmos React applications built on Pega Platform version 8.7 do not support language packs for version 8.6, or for section-based 8.7 applications.
  1. In the navigation pane of App Studio, click SettingsLocalization.
  2. On the Translation packs tab, in the row that represents the language of your translation, in the Status column, click the More icon.
    The More icon on the Translation packs tab
    The More icon is in the last column of the row representing each target language.
  3. Click Import translation.
  4. In the Import translation modal dialog box, upload the file with the translation.
  5. Click Next.
    Tip: If the system shows import errors, check the ruleset for locked rules.
  6. When the import completes, click Done.
    Result: The status of the translation changes to Resolved.

Creating localization rules in Dev Studio

Gain a more granular level of control over the localization process by generating localization rules in Dev Studio. For example, you can use localization rules to manually add properties to a translation package, even when the system omits them.

Before you begin: Ensure that you are working in a development branch. For more information, see Developing applications in branches.
  1. In the header of Dev Studio, click ConfigureUser InterfaceApplication ReadinessConstellation.
  2. In the Upgrade section, in the Upgrade branch name list, select the branch where you work.
  3. Click Upgrade views.
    Result: The system launches an upgrade process that generates localization rules for all views in your application.

Localizing controls that rely on data pages

Ensure that your interface does not include untranslated picklists and radio buttons by adding controls that source entries from data pages to the translation package. Because data pages are empty when the system generates the translation package, you must add their content manually.

Before you begin:
  1. In the navigation pane of App Studio, click SettingsLocalization.
  2. On the Additional text tab, find the data page related to the control that you want to localize, and then click the MoreEdit record icon.
    The More icon on the Additional text tab
    The More icon is in the last column of the row representing each field.
  3. In the Edit record modal dialog box, populate the data page with the values that you want to localize by entering each value in a separate row.
    For example: Your vehicle loan application includes a Vehicle type picklist that lists the following vehicle types: car, van, truck, and motorcycle. The vehicle types are sourced from the D_AutoLoanList data page. You want to include the vehicle types values in the translation package. In the Edit record, you then enter the same values:
    Car
Van
Truck
Motorcycle
  4. Click Submit.
What to do next: Rebuild the translation package. For more information, see Creating a translation package in Cosmos React.

Localizing properties with more than one value

Provide your localization team with access to all properties and ensure that no element of your interface remains untranslated. When generating a translation package, the system omits local properties that have multiple values, such as properties associated with picklists. You can add these properties to the translation package manually by editing their localization file in Dev Studio.

Before you begin:
  1. In the navigation pane of Dev Studio, click App.
  2. Click Branches.
  3. In the application node, expand the branch where you work, and then expand the Localization node.
    Result: The node displays a list of localization rules for the application.
    Localization node in a sample application
    The Compass application includes a branch called "localization" that hosts Localization nodes with localization rules.
  4. On the localization rule list, select the rule associated with the property that you want to include in the translation package.
  5. On the rule form, click Check out.
  6. On the Default tab, select the Mark as editable checkbox.
  7. In the Locale Json field, enter the values that you want to translate in a JSON form.
    For example: Your mortgage application might include a drop-down where you select what kind of asset the loan is for. In this scenario, your JSON file could have the following structure:
    {  
    "AssetType": {  
"fields": {
        "House": "House",   
        "Apartment": "Apartment",   
        "Land": "Land" 
}
    }  
}
  8. On the rule form, click Save, and then click Check in.
  9. In the Check in modal dialog box, in the Check-in comments field, enter a comment that describes your changes to the rule.
  10. Click Check in.

Creating localization Rules manually

Create localization Rules for components that are not yet referenced in your application to ensure that they too are covered by the localization effort. For example, if a Data Page is not referenced by any View, you can create a localization Rule for that Data Page manually.

  1. In the navigation pane of Dev Studio, click App.
  2. In the pane on the left-side of your window, click Classes.
  3. Search for and open the Rule-UI-Localization Class.
  4. On the Localization tab, click Create.
  5. On the New tab, enter the configuration information for the new localization Rule:
    1. In the Label field, enter the name of the component that you want to localize.
      For example: Enter D_Sample_DataPage.
    2. In the Context field, enter the type of a component that you want to localize.
      For example: Enter datapage.
    3. In the Apply to (Class) field, enter @baseclass.
  6. Click Create and open.
    Result: A tab opens with the new localization Rule.
  7. Click Save.
Result: Localization Rules that you create manually appear in the Additional text tab of the Localization landing page.

Tags

Pega Platform 8.7 User Experience

Have a question? Get answers now.

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

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

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

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us