International Language Support (Translations)

Owned by David Russo
Last updated: Aug 16, 2023 by Jessica Tomkins
7 min read

 

Overview

Profound UI provides built in capability for translating constant strings (such as field labels, grid headings, tool tips, etc.) in your applications. Based on the user’s language setting, Profound UI can dynamically populate various widget properties at runtime to accomplish this.

Since translation data is stored in Unicode, Profound UI applications can support multiple languages under the same server configuration / environment.

Translation Database

Translations are stored in database file PUITRANSP in the product installation library. Each record in this database represents a word or phrase that can have translations in several languages. The field descriptions are as follows:

Phrase id (TRID): This is a unique identifier that represents a word or phrase.
Language code (TRLANG): The format of the language code field is a two-character ISO language code, followed by an underscore, followed by a two-character ISO country code.

Example codes: 

  • en_US = English, United States

  • en_GB = English, Great Britain

  • de_DE = German, Germany

  • de_CH = German, Switzerland

Phrase (TRPHRASE): The word or phrase text, encoded in UTF-16 (CCSID 1200).

Records having the same phrase id are associated as translations of the same word or phrase in different languages.

To translate Profound UI widget property text, a phrase id is associated with the property, rather than the phrase text. So, it’s possible to support words that are homonyms in one language, but not in another.

Maintenance of Translation Database

Starting with Profound UI Version 5, Fix Pack 10.0, you can use the Work with Language File Tool to maintain your translation database. You can also automatically create entries from existing Profound UI Rich Display Files using the PUITRNSRC command (see below).

Since the words or phrases are stored in Unicode / “graphic” fields, some older DB editing tools (such as DFU) will not work with the file.

IBM-provided DB editors that will work with this file include the table editor in IBM i Navigator (the PC-side GUI version) and Data Studio for Rational Developer.

Translating Widget Properties in the Designer

The language translation features will not be available in the Designer unless there are records in PUITRANSP. If adding records to PUITRANSP for the first time while the Designer is open, it will be necessary to refresh the Designer page before the language translation features will become available.

Before you can work with translations in the Designer, you must select the current language you are working with. This controls what language is used when searching for words or phrases in the translation database, and also how the words or phrases are displayed in the Designer.

You can select the current language from the Home section of the toolbar.

Each language for which there are translations on file will be displayed. If adding translations in new languages while the Designer is open, you must refresh the Designer page to make them available. Once selected, your language setting will be stored permanently in your web browser until you clear browsing data. If using the Designer with multiple web browsers, you must select the language in each browser that you use.

The following widget properties display text to the user, and can be translated:

  • value

  • on text

  • off text

  • html

  • alternate text

  • label

  • empty text

  • placeholder

  • choices

  • blank option label

  • names

  • tab names

  • tool tip

  • column headings

  • csv file name

  • header text

  • section names

Once the language is selected, you can activate the Translation Settings dialog for a widget property by using the button located next to the Field Binding button in the property name:

On the Translation Settings dialog, you can locate a phrase by typing into the text box. Phrases matching your query (in your selected language) will be suggested.

After selecting a phrase, any translations on file will be displayed below.

For properties that accept a comma-separated list or JSON array (such as drop down 'choices' or grid 'column headings', additional translations can be added to the list by clicking on the Add button. Also, it's possible to include a blank entry in the list (such as a blank grid header) using the 'blank entry' checkbox that appears for this type of property:

After completing the dialog, the phrase (in your selected language) will be displayed in purple in the Properties Window.

Also, the phrase will appear on the widget in the design canvas, enclosed in brackets:

Automatically Translating Widget Properties using the PUITRNSRC Command

The CL command PUITRNSRC can be used to automatically setup Translation Settings for existing Profound UI Rich Display File DDS source. The command can also optionally produce translation database entries from the DDS source, if it encounters words or phrases which do not exist in the translation database.

The command can be run on a single source member, or on a generic member name or *ALL members within a given source file.

The command will find any constant strings assigned to any of the translatable widget properties listed above. If the word or phrase is found in the translation database, the constant string in the DDS is replaced with a reference to the associated phrase id.

Command parameters:

  • FROMFILE / LIBRARY: The input source file to process. The source file can be qualified with a library, or *LIBL or *CURLIB can be used.

  • FROMMBR: The input member name to process. A generic member name or *ALL can also be used.

  • TOFILE / LIBRARY: The output source file to write modified source members to. The source file can be qualified with a library, or *LIBL or *CURLIB can be used.
    Note: It is valid to use the same file for output as for input. However, keep in mind that this command will modify your source code.

  • TOMBR: The output source member name. Special value *FROMMBR can be specified to use the same member name as the input member. *FROMMBR must be specified when using a generic name or *ALL for FROMMBR.

  • LANG: The language code. This must be specified in the same format as documented above for field TRLANG in the translation database file.
    This parameter specifies what language to use when comparing constant strings in the DDS code to records in the translation database file.

  • GEN: Generate translation database records. When *YES is specified, translation database records will be created automatically when strings are encountered in the DDS which do not exist in the translation database file.
    When *NO is specified, no records will be created in the translation database file, and only widget properties for which existing translations exist will be modified.

The command produces two print reports which should be analyzed after processing:

  • PUITRNOUT: This report is a simple listing of input members processed vs. output members produced. If the count of input members vs. output members does not match, you should examine the job log for details on failure to process specific members.

  • PUITRNSTR: This report is a listing of ALL strings encountered in the DDS code for which no translation database record existed, regardless of what value was specified for the GEN parameter. If GEN(*YES) was specified, then the listed records were created by the command, and the associated widget properties were modified. If GEN(*NO) was specified, then no records were created and the associated widget properties were not modified.
    Also, a string's status can be listed as 'Duplicate' in this report. In this case, the command found more than one record for the given string, in the given language. This can be the case for homonyms. In this case, the command cannot decide which phrase to use, so no action is performed. The appropriate phrase would have to be selected manually in the designer.

Note: PUITRNSRC does not compile the output source members. They will have to be compiled before translation can occur at runtime.

Runtime Processing

At runtime, Profound UI will default the language setting, based on the job's 'language identifier' attribute. These values are specific to IBM i, and must be mapped to the ISO codes used in the translation database. Profound UI performs the following mappings:

IBM i Language Id to ISO code:

  • ARA → ar_EG

  • NLB → nl_BE

  • FRB → fr_BE

  • PTB → pt_BR

  • FRC → fr_CA

  • NLD → nl_NL

  • ENA → en_AU

  • FRA → fr_FR

  • DEU → de_DE

  • HEB → he_IL

  • ITA → it_IT

  • PTG → pt_PT

  • ESP → es_ES

  • FRS → fr_CH

  • DES → de_CH

  • ITS → it_CH

  • ENG → en_GB

  • ENU → en_US

  • All others: → en_US

If the above mappings are sufficient, then no other action is necessary.

If an alternate language setting is required which is not accomplished by the above, then the language setting can also be set by running the PUISETLANG command in the job.

For example:

PUISETLANG LANG(it_IT)

Once the desired language is set, Profound UI will automatically translate any widget properties that are associated with phrase identifiers to the appropriate text from the translation database.

Starting with Profound UI version 6, fix pack 8.0, you may set the language ID via the 'lang' query string parameter as an alternative to the PUISETLANG command.

Note: Profound UI will check for the job language identifier only once, the first time that it encounters translated widget properties in the job. So, it's not possible to change the language by changing the job language identifier after Profound UI has already performed translations in the job. In this case, the PUISETLANG command must be used to change the language.

If any translation data is missing when a screen is rendered, an alert box will display containing information about the missing phrase text and associated widget properties: