This documentation supports the 22.1 version of Action Request System.
To view an earlier version, select the version from the Product version menu.

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.

Related topics

Progressive web application screens

Localizing BMC Remedy AR System applications

Using the localization toolkit (Video) Open link

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.

Important

  • While exporting strings for localization, you can opt to export only the items that are related with Progressive Views.
  • The time taken to extract or export strings depends upon the number of items involved. Therefore, it can take a while to export large number of items, for example, 1000 or 2000.
  • You cannot use a TSV file to import translations through the localization toolkit. This file is generated specifically for the AR System Message Catalog form. Use the command-line utility to import a TSV file in to the AR System Message Catalog form after translation.

 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:

Column nameDescription
Message-Type

The type of the object for which the string is extracted.

See Types of objects exported.

Form Name/Message IDThe name of the Form or Active Link or Filter
VUI IDThe View ID of the Form
Field ID/Message NumField ID or message number from the Active Link or Filter actions
Source Text

The string to be localized. It includes the following:

  • Field labels, such as Data Fields, Control Fields, and Selection Fields
  • Selection alias for fields such as Radio button and Drop-down list
  • Help text from forms and fields
  • Alternative text for fields
  • Message strings from Active Links and Filters

Important

In a TSV file, characters such as comma (,) are replaced by tags such as <comma> in strings.

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:

CharacterDescriptionTag used
\r\nCarriage return and new line<crlf>
\nNew line<lf>
\rCarriage return<cr>
,Comma<comma>

Types of objects exported

Message typeType of objectDescription of the string
0System MessageBelongs to a System message action.
1Active Link MessageBelongs to an Active Link message action.
2Filter MessageBelongs to a Filter message action.
3Active Link Help TextBelongs to the Help Text property of an Active Link.
4Form Help TextBelongs to the Help Text property of a Form.
5Field Help TextBelongs to the Help Text property of a Field.
6Container DescriptionBelongs to the Description property of a Container.
7List Menu DefinitionBelongs to the Definition property of a List Menu.
8External ReportBelongs to an External Report.
9Container LabelBelongs to the Label property of a Container.
10Container HelpBelongs to the Help property of a Container.
11Application HelpBelongs to the Help property of an Application.
12Application AboutBelongs to the About property of an Application.
13Application Help IndexBelongs to the Help Index property of an Application.
14Flashboards System MessageBelongs to the System Message property of Flashboards.
15Flashboards LabelBelongs to the Label property of Flashboards.
16Field Label

Belongs to the Label property of a Field.

17Field Help TextBelongs to the Help Text property of a Field.
18Alternative TextBelongs to the Alternative Text property of a Field.
19Selection AliasBelongs to the Alias property of a Selection Field.
20Label for Empty ValueBelongs to the Empty Value property of a Label.
21Alias SingularBelongs to the Singular property of an Alias Field.
22Alias PluralBelongs to the Plural property of an Alias Field.
23Alias Short SingularBelongs to the Short Singular property of an Alias Field.
24Alias Short PluralBelongs to the Short Plural property of an Alias Field.
25Entrypoint Label Default NewBelongs to the Default New property of an Entrypoint Label.
26Entrypoint Label Default SearchBelongs to the Default Search property of an Entrypoint Label.
27Attach Add LabelBelongs to the Add Label property of an Attach Field.
28Attach Delete LabelBelongs to the Delete Label property of an Attach Field.
29Attach Display LabelBelongs to the Display Label property of an Attach Field.
30Attach Save LabelBelongs to the Save Label property of an Attach Field.
31Attach File Name TitleBelongs to the File Name Title property of an Attach Field.
32Attach File Size TitleBelongs to the File Size Title property of an Attach Field.
33Attach Label TitleBelongs to the Label Title property of an Attach Field.
34Attach Deselect LabelBelongs to the Deselect Label property of an Attach Field.
35Button TextBelongs to the Text property of a Button.
36Menu TextBelongs to the Text property of a Menu.
37Menu HelpBelongs to the Help property of a Menu.
38TooltipBelongs to the Text property of a Button.
39HTML TextBelongs to the Text property of HTML.
40Enums LabelsBelongs to the Labels property of an Enumeration.
41TextBelongs to the Text property.
42Table Selection Column LabelBelongs to the Column Label property of a Table Selection.
43Table Root Node Alternative TextBelongs to the Alternative Text property of a Table Root Node.
44Table Entries ReturnedBelongs to the Entries Returned property of a Table.
45Table RefreshBelongs to the Refresh property of a Table.
46Table DeleteBelongs to the Delete property of a Table.
47Table ReportBelongs to the Report property of a Table.
48Table Select AllBelongs to the Select All property of a Table.
49Table Deselect AllBelongs to the Deselect All property of a Table.
50Table PreferenceBelongs to the Preference property of a Table.
51Table Chunk NextBelongs to the Chunk Next property of a Table.
52Table Chunk PreviousBelongs to the Chunk Previous property of a Table.
53Row LabelBelongs to the Label property of a Row.
54Row Label PluralBelongs to the Label Plural property of a Row.
55Table Auto RefreshBelongs to the Auto Refresh property of a Table.
56Table UnreadBelongs to the Unread property of a Table.
57Table ReadBelongs to the Read property of a Table.
58Table Not RefreshBelongs to the Not Refresh property of a Table.
59Tree Table Custom ValueBelongs to the Custom Value property of a Tree Table.
101MessageBelongs to the Message property.
102DataBelongs to the Data property.
103Entry PointBelongs to the Entry Point property.
104MenuBelongs to the Menu property.
105DescriptionBelongs to the Description property.
106Guide Help TextBelongs to the Help Text property of a Guide.
107App Help TextBelongs to the Help Text property of an Application.

To translate the strings in a TSV file

Send the exported TSV file to a vendor for translation. 

Best practice

For accurate translation, we recommend that you send the file to professional translators. (Open source and commercial editors are available for purchase by several third-party vendors.)
After the translation is completed, the TSV file has an additional sixth column which contains all the translations. The TSV file contains localized strings starting from the sixth column. That is, each column represents a single locale. 

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 :

    ParameterDescription
    -xName 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.

    -fName 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.

Was this page helpful? Yes No Submitting... Thank you

Comments