Skip to main content


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

Localizing mobile apps for international audiences

Updated on May 6, 2021

Applicable to Theme Cosmos applications

Make your mobile app more accessible for your international audiences by localizing the UI text for specific countries and regions.

For example, uPlus bank plans to open a new company branch in Spain. To ensure that employees can efficiently submit local expenses in their native language, uPlus bank translates the UI labels and messages of their Pega app into Spanish and uploads the compressed localization package to Pega Platform.

Note: The UI labels and messages that you translate as part of the localization package are applied based on the locale of the mobile device. The remaining mobile UI elements (such as navigation bar labels, list titles, and tabs) and elements of the web UI are localized based on the operator's locale.

    Downloading the template localization file

  1. Go to Branding assets templates for Pega Mobile Client and download the simplified assets .zip file that matches your version of Pega Mobile Client.
  2. Extract the contents of the .zip file.

    3. Creating localization files

  3. Open the folder with the extracted files.
  4. Translate the UI labels and messages:
    ChoicesActions
    Translate UI text for Android apps
    1. Open the android folder.
    2. Create a copy of the values-en folder.
      The folder contains the strings.xml file. Make sure that you copy the folder together with the file.
    3. Rename the folder that you copied by replacing en in the folder name with the ISO-639-1 code of the target language.For example: A uPlus mobile app developer working on a Spanish version of the mobile app renames the folder to values-es.
    4. In the folder that you copied and renamed, open the strings.xml file.
    5. Translate the English UI text into the target language.
      Translating the English UI text into Spanish for Android apps
      The user edits the strings so that they contain the Spanish equivalent of the original English UI text.
    6. After translating the UI text, save the strings.xml file.
    7. If you want to include another localization pack, repeat the above steps for each new language.
    Translate UI text for iOS apps
    1. Open the ios folder.
    2. Create a copy of the en.lproj folder.
      The folder contains the localizable.strings file. Make sure that you copy the folder together with the file.
    3. Rename the folder that you copied by replacing en in the folder name with the ISO-639-1 code of the target language.For example: A uPlus mobile app developer working on a Spanish version of the mobile app, renames the folder to es.lproj.
    4. In the folder that you copied and renamed, open the localizable.strings file.
    5. Translate the English UI text into the target language.
      Translating the English UI text into Spanish for iOS apps
      The user edits the strings so that they contain the Spanish equivalent of the original English UI text.
    6. After translating the UI text, save the localizable.strings file.
    7. If you want to include another localization pack, repeat the above steps for each new language.

    5. Uploading the localization package to Pega Platform

  5. Select the folders that you extracted from the .zip file that now contain the localization files, and then compress them into a single .zip file.
  6. Open your mobile channel:
    1. In the navigation pane of App Studio, click Channels.
    2. In the Current channel interfaces section, click the tile that represents a mobile channel for your app.
  7. On the mobile channel page, on the Layout tab, click Branding.
  8. In the Branding section, click the Configure advanced branding icon, and then select the Advanced Branding check box.
  9. In the Upload custom branding file section, click Choose file, and then select the .zip file that contains the localization files.
  10. Confirm your selection by clicking OK.
  11. Click Save.

Configuring localization for offline-enabled mobile apps

Applicable to Theme Cosmos applications

Configure localization in your offline-enabled mobile app to give users a consistent experience regardless of network connection status, and enable them to change languages within the app at run time without losing data.

For example, when surveying individuals who speak different languages, survey takers can easily switch languages by selecting a language option in the language list of the offline-enabled app.
Before you begin:
  • Define the languages that your users speak and find out which language packs are in your system. To acquire language packs, contact Global Client Support.
  • Install the language packs that you need. For more information, see Installing Pega language packs.
  • Localize your application for the languages that you need. For more information, see Internationalization and localization.

By default, when you configure offline localization for your app, the system packages and makes available offline only those field values and paragraphs that the UI directly references. The system also packages field values with parameters.

Auto-generated controls also support offline localization. For more information, see Creating auto-generated custom controls.

  1. In the header of Dev Studio, click ConfigureMobileOffline configuration.
  2. On the Offline configuration tab, in the Configuration template section, click the template that you want to use with your offline-enabled mobile app.
  3. On the Resources tab, add the locales that you want to support in offline mode:
    1. In the Locales section, click Add locale.
    2. In the dialog box, enter the names of the locales that you want to add, and then click Add.
    Note: You can add multiple locales by adding the ISO codes for standard languages and dialects. For example, you can add de_DE for German, es_ES for Spanish, and zh_CN for simplified Chinese.
  4. In the upper-right corner of the offline configuration template form, click Save.
  5. Decide how you want users to switch locales at run time, and based on your choice, add a button, a link, or a drop-down list to your section.
    For more information, see Adding UI components to a view.
  6. Configure the following action sets for your control:

    For more information about configuring action sets for a control, see Adding action sets to a control.

    1. In the action set table, click Add an event, and then based on your choice of control, define the event:
      • For a Button or Link control, select Click.
      • For a Dropdown control, select Change.
    2. Click Add an action, and then select the Run script action.
    3. In the Function name field, enter the switchLocale function to run the provided API.
      Note: The pega.clientTools.switchLocale(newLocale) API works only for cases that are marked as offline-enabled.
    4. In the Parameters table, define a parameter name and value. For example, enter Locale and de_DE.
    5. Configure the Refresh-Other section action set.
      For more information, see Adding action sets to a control.
    6. Click Submit.
  7. Optional: To package and make available offline field values that are no UI section directly references, for example, the case status, or to package field values that are dynamically resolved (through a property reference), add these field values to the allow list by performing the following actions:
    1. On the Allow list tab, click Add field values.
    2. Populate the auto-complete field with the field values that the UI does not directly references but which you want to include in packaging, and then click Add.For example: To package the ButtonLabel Add Item field value, which is used in a section from the Work- class, select the AddItem field value from the list.
    3. If multiple classes reference a field value, click Add field values with multiple runtime class.
    4. Populate the Field Value auto-complete field with the field value.
    5. In the Run time classes list, select the classes that reference the field value, and then click Add. For example: For the ActionPrompt Delete item field value, which you access from the section in the Work- and Work-Cover classes, make the following entries:

      @BASECLASS!PYACTIONPROMPT!DELETE ITEM"Work-"

      @BASECLASS!PYACTIONPROMPT!DELETE ITEM"Work-Cover"

    Result: The field values for all the locales that the template configuration includes are downloaded to the client store when the mobile app performs a full synchronization. For more information, see Data synchronization in offline mode.

Debugging techniques in offline localization

Applicable to Theme Cosmos applications

Ensure that offline localization of your app works as intended by applying the recommended debugging techniques.

Your application UI is not translated in offline mode

Resolving issues with offline localization

  1. In Dev Studio, check the configuration of the field value associated with the untranslated text to determine whether the field value is dynamic (a property reference), or static.
    Note: Generally, field values associated with out-of-the-box controls or that are directly referenced in the UI are static. Field values that are referenced in other ways are dynamic.
  2. Depending on how the system references the field value, ensure that you have the correct configuration:
    • If the text is retrieved dynamically from a property reference, ensure that the required field values are present in the pyFieldValueWhitelistForOffline HTML rule. For more information about adding dynamically referenced field values to the allow list, see Configuring localization for offline-enabled mobile apps.
    • If the field value that is associated with the untranslated text is static, check the section and the field value classes. Ensure that the field value is present in the section class or in the inheritance of the section class.
  3. If steps 1 and 2 are ineffective, in the console, run the following script to fetch the localization object, and then verify whether the required field values are available in the correct class:
    • To fetch all the field values, enter:
      pega.offline.clientstorehelper.getLocaleData(localeName,
 /* success */
 function(data) {
 console.log(data);
 },
 /* failure */
 function(error) {
 console.log("An error has occurred");
 }
 );
    • To fetch a single field value, enter:
      pega.clientTools.getLocalizedTextForString(fieldName, FieldValue)
    • To fetch a paragraph, enter:
      pega.offline.clientstorehelper.getParagraph(pxInsName, /* success */
 function(data) {
 console.log(data);
 },
 /* failure */
 function(error) {
 console.log("An error has occurred");
 }
);

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