Localizing a Progressive Web Application

BMC provides a localization toolkit in  Developer Studio  to localize your  AR System  applications from English to other supported locales. Use the localization toolkit and the AR System Message Catalog form to localize your Progressive Web Application (PWA).

The localization toolkit is used to extract the localizable strings from the objects. After extracting, export the strings to a Tab Separated Values (TSV) file, translate the strings and import the translated strings into the AR System Message Catalog form by using the ARMsgCatalogEntryCreator utility. This utility creates new records in the AR System Message Catalog form. The PWA screens use these records in the AR System Message Catalog form and display localized strings based on the browser locale.

To localize a progressive web application, you don't need the static, locale-specific views created by the localization toolkit for standard applications. For PWA, the localization toolkit is used only to extract the localizable strings from the objects and to export the strings into a TSV file. 

PWA uses the AR System Message Catalog form to store and retrieve translations as required. Thus, as a Remedy developer, you do not need to create locale-specific views for the same objects by using the new form.

If you are a BMC Helix ITSM  user, you must configure a client gateway to access and customize your application by using Developer Studio .

Review the Best practices for localizing a progressive web application section below before you perform the localization process.

The following video (7:31) provides an overview of how to localize a Progressive Web Application.

 https://youtu.be/e2tOOdpBAB0

PWA supports the following languages out-of-the-box:

• en—English (default)
• de—German
• es—Spanish
• fr—French
• iw_IL—Hebrew
• it—Italian
• ja- Japanese
• ko-Korean
• pt_BR—Portuguese 
• ru—Russian
• zh_CN—Chinese

If you want to localize your Progressive Web Application in any other language, use the following localization process.

Localization process

Perform the following steps in Developer Studio  to complete the localization process:

1. Prepare your application that you want to localize.
2. Install the localization toolkit.
3. Set a root folder.

4. Create a package definition for the forms that you want to localize.

5. Extract the strings that you want to localize.

6. Export the strings in a file that has the default Tab Separated Values (TSV) format.

7. Translate the strings in the TSV file.
8. Import the TSV file to the AR System Message Catalog form.

To prepare your application that you want to localize

To be ready for localization, your server must be configured for localization. Additionally, applications must have the correct localization properties set for forms, their associated views, and fields. By default, all forms, views, and fields are configured to be localized, so you should not have to manually set each property. Conversely, if you have specific forms, views, or fields that you do not want localized, set the property accordingly.

For instructions, see Preparing your application to be localized.

To install the localization toolkit

When you install the localization toolkit, the localization toolkit files are added to the DeveloperStudio folder of your AR System  installation. (The default installation directory is C:\Program Files\BMC Software\ARSystem\ DeveloperStudio.)

The localization toolkit plug-ins are placed in the plugins folder with the other Developer Studio  plug-ins. A Localization Package Definitions branch is added to each server in the AR System Navigator in  Developer Studio .

For instructions, see Installing the localization toolkit.

To set a root folder

To begin the localization process, set a root folder, which stores:

• The localization database (l10n.db )
• The log file that logs the translation progress (l10n.log )
• Package definition files that you create for translation

The default root folder is the BMCRemedyDeveloperStudioInstallDir\workspace\l10N folder.

For instructions, see Setting a root folder.

To create a package definitions for the forms

The Localization Package Definition editor in Developer Studio  makes it easy to create a localization package definition for your application and any other forms that you want in the package definition.

For instructions, see Creating a localization package definition.

To extract the strings that you want to localize

After you create a localization package definition, you can extract the strings for localization into the localization database (l10n.db in the root folder).

For instructions, see Extracting the strings for localization.

To export the extracted strings to a TSV file

For Progressive Views, you must use the TSV format.

 Perform the following steps:

1. In Developer Studio , open the localization package definition.
2. Click Export Strings.
3. In the Localization Item Export dialog box, enter the full path to a target .tsv file that will contain the extracted strings.
   If the path you enter does not have a TSV file, then it is created. If you specify a full path, the file is created at that location. If you specify only a file name, the file is created in the root folder.
   The default root folder is the BMCRemedyDeveloperStudioInstallDir\workspace\l10N folder.
4. Select the locale you want to export.
5. Select the state of the strings that you want to export.

6. Click OK.
   Only those items that are set to the state you selected in step 5 (for example, "Ready to Translate") are exported to the .tsv file. For more information, see Reviewing the status of the translation progress.

   Tip

   For each locale, add a new column with localized strings that map to the Source Text column to the exported file. Add the locale code to the header of the new localized column.

Tab Separated Values (TSV) file

The following image shows a sample TSV file before translation:

The following table provides information about the columns in the exported TSV file:

Because TSV is a delimiter-separated file, characters such as commas or new lines in the file result in localization strings occupying multiple cells and rows instead of just one cell. Therefore, these are replaced by tags as shown in the following table:

Types of objects exported

To translate the strings in a TSV file

Send the exported TSV file to a vendor for translation. 

The following image shows a sample TSV file after translation:

To import a TSV file containing translated strings to the AR System Message Catalog Form

You can use the ARMsgCatalogEntryCreator utility that reads the TSV file and creates or updates an entry in the AR System Message Catalog form. The ARMsgCatalogEntryCreator utility accepts only a TSV file as an input.

Perform the following steps to import a TSV file to the AR System Message Catalog form using the ARMsgCatalogEntryCreator utility:

1. Before you use this utility, sort the TSV file four times—first by the Form Name column, next by the Field ID column, next by the View ID column, and finally by the Message Type column.
   

   Important

   Make sure that your AR System server supports the locale that you want to translate to. Otherwise, records with corrupted data, instead of the actual data, might get created in the AR System Message Catalog form.

2. Navigate to <ARSystemInstallDir>/ARSystem/artools and find the armsgcatalogentrycreator.bat file.

3. From a command prompt, run the armsgcatalogentrycreator.bat file by using the following command:
   

   ARMsgCatalogEntryCreator utility command syntax

   armsgcatalogentrycreator.bat [-x] [-u] [-p] [-t] [-f]

   ARMsgCatalogEntryCreator utility command example

   armsgcatalogentrycreator.bat -f <Location of TSV file>\Translations.tsv -u <Username> -x <Server Name>

   The following table describes the inputs for the Command Line Interface (CLI) and parameters for connecting to the AR System :

   Parameter	Description
   -x	Name of the server to connect to.
   -u	Name that identifies the user account for the AR System server .
   -p	Password for the user account. If you have a blank password, you can ignore this option.
   -t	TCP port number to connect to. If the port number is unknown, use -t 0.
   -f	Name of the TSV file.

   Depending upon the row data, an entry is created or updated. For every locale, a separate entry is created per row. For example, a single row entry in the TSV file with three translations (that is, three different locales) creates three new entries for that string.

   Important

   The Selection Alias type of object (Message type 19) is handled in a special way. Suppose, there is a Selection Alias type of object called "Status" that has five aliases as New, Assigned, Fixed, Rejected, and Close. For each alias, instead of creating a separate entry, the aliases are combined into a single record.

   For example:

   {"New":"Neu","Assigned":"Zugewiesen","Fixed":"Fest","Rejected":"Abgelehnt","Closed":"Geschlossen"}

   In this example, each alias is separated by a comma (,) and contains two values—the left one is the actual string that is being exported and the right one is the translated string.

   Important

   In the TSV file, columns after the Source Text column hold the translated data. If the translated data column for a language has the same string as the Source Text (English) column, the ARMsgCatalogEntryCreator utility does not create a record for the same string in the AR System Message Catalog Form.

   For example, if you have a string 'ALL' in the English and the Russian language columns, the utility skips creating a new record for the string 'ALL' for the Russian language column.

   This is applicable for all message types except 19 (Selection Field) as all the values are combined in a single record.

Best practices for localizing a progressive web application

• Use independent forms only so that the related Active Links and Filters are also considered.
• For the form fields that you want to localize, set the value of the "Localize Label" property in Display Properties to True.
• When you delete a package definition, the package definition is deleted, but the extracted strings are not deleted from the localization database. If you create a package definition with the same name as the deleted one and export, you get the extracted strings from the deleted package definition as well. To avoid this issue, we recommend that you explicitly delete those strings from the database.