Summary

This article covers supporting multiple languages.

Table of Contents

• Definitions
  • Multi-lingual Study
  • Internationalization, I18n
  • Localization, L10n
• Supported Languages
• Internationalization Process
  • Configure App Properties
    • Property i18nPluginID
    • Property l10nDefaultLang
    • Property l10nLang
    • Example Configuration
  • PDF Encoding Properties
  • Compile Data Architect File
  • Decompile Data Architect File
  • Using Visual Designer for Trial Design
  • Add Additional Internationalization Properties
    • App Properties Text
    • Form Renaming
      • Add i18n keys to the forms
      • Add Localization Properties
    • Scripting
      • Add i18n keys to the script
      • Add Localization Properties
  • Translate All Localization Properties
    • Compile List of Localization Properties
    • Translate the Localization Properties List
    • Merge Translated List Into Data Architect File
• Keys and Properties
  • Internationalization Keys (I18n Keys)
    • Examples
    • Invalid i18n Keys
  • Localization Properties (l10n Properties)
    • Examples
• Tips and Tricks
  • Test the Clinical Trial
  • I18n Keys Ending With a Dot
  • Excel and the ‘ as Leading Character
  • Excel and the @ as Leading Character
  • Inconsistent String Values – Generation of I18n keys

Clinical trials can be configured to support multiple languages. The language that is displayed to a user depends on the setting of the “preferred language” in the user’s profile. To a large extent, the designer can configure a multi-lingual study in the same way as a trial having only a single language. The localization to a different language is performed with a set of properties that can be easily extracted and merged for the localization process.

Definitions

Refer to this section when you are unsure about a specific term or system variable.

Multi-lingual Study

A multi-lingual study can be displayed in one of multiple different languages to a user. There need to be at least two different languages.

Internationalization, I18n

Internationalization refers to the preparation of program code or design data in order to support multiple languages for the end user. The abbreviation is i18n, which means that an “I” is followed by 18 other characters and an “N.”

Localization, L10n

Localization refers to the preparation of internationalized material for a specific language. For each additional language an additional localization step is needed. In general this will mean the translation into the new language. The abbreviation is l10n, which means that an “L” is followed by 10 other characters and an “N.”

Supported Languages

Languages for a clinical trial are restricted to the languages that can be selected from the user’s profile. The following is a list of currently supported languages with their codes. If a language is needed that is not in this list, contact Fountayn to request that the new language be added to the list.

Internationalization Process

A multi-lingual study is designed in the same way as a single-language trial. In general, the terms for the default language will be placed in the same manner as they would for a single-language trial. After configuring the trial for the default language, the Data Architect file is compiled and decompiled. During the decompiling process, the system will handle most of the internationalization process automatically. After the internationalization of special cases is added manually, the Data Architect file is ready for translation. The following diagram summarizes the internationalization and translation processes.

Configure App Properties

For each multi-lingual study, the following properties need to be set on the App Properties worksheet.

Property i18nPluginID

This property specifies the key used throughout the study to designate the use of internationalization. Generally, this should be a project ID value provided by Fountayn, because it is short and can be used to differentiate between all studies in the entire platform. No two studies have the same Fountayn project ID. Contact Fountayn if the plug-in ID should be different from the the Fountayn project ID.

Note: Never copy the i18n plug-in ID configuration from one study to another.

Property l10nDefaultLang

This property specifies the default language for the study and is the language that is used while designing the study. Only a code for a Supported Language can be used here.

Property l10nLang<pos>

This property specifies the other languages that need to be configured for the study. ‘<pos>’ signifies that this property is a numbered property that needs to end in a number. The numbers should be ordered sequentially beginning with the number, 1. Only a code for a Supported Language can be used.

Example: The first additional language is specified with property l10nLang1. The second additional language is specified with the property, l10nLang2.

Example Configuration

The following example is configured for a study with the project ID, XXX09100. The default language is English. The additional language that needs to be configured for the study is German.

Note: Before proceeding, make a backup copy of the Data Architect file.

PDF Encoding Properties

PDF Encoding properties may need to be set to ensure proper display of characters from different languages. See App Properties for additional information.

Compile Data Architect File

1. In the Trial Manager select ‘Design’ for the study that needs internationalization.
2. In the Form Links table, select ‘Compile Architect.’
3. Complete the Compile form.
4. Click the ‘Compile’ button.
5. Assure that there were no compile errors.

Decompile Data Architect File

1. In the Form Links table, select ‘Edit Architect.’
2. Select the Data Architect file that needs internationalization.
3. In the Actions drop down menu, select ‘Open Data Architect File.’
4. Click the ‘Go’ button to download the new decompiled file.
5. Open the decompiled Data Architect file.

All of the basic text included in the Data Architect file such as questions, role names and form names have been replaced with internationalization keys. The App Properties worksheet also has new localization properties as shown in the following example.

In this Data Architect file, the default language is English, so most of the English localization values were completed automatically. The German localization values take the form {de, sample text} to designate the language and the text that needs to be translated.

Using Visual Designer for Trial Design

When using the Visual Designer for trial design, if you wish to add Multi-lingual to a study already in the design process AFTER enabling the multi-lingual properties, additional steps will need to be taken. 

1. Commit the version in Visual Designer.
2. Decompile the DataArchitect in the Trial Manager. 
3. Commit the DataArchitect in Trial Manager to turn the properties on. 

Note: There is no need to do the extra steps if you start with Multi-lingual properties at the first design process in Visual Designer. 

Add Additional Internationalization Properties

While decompiling will handle most of the text, there are some special cases that need to be configured manually. The following sections highlight these special cases and provide an example of how to handle them. The Tips and Tricks section may also be helpful when defining internationalization and localization properties.

App Properties Text

There are some app properties containing text that are displayed in the system. Currently the application does not have automatic i18n support for these properties.

Assume that the clinical trial has the Fountayn project ID, XXX09100, and that the property, column4Header, needs to be internationalized. In the following example, the value of the property is set to an internationalization key and two localization properties are added. Depending on the language selected when viewing the system, one of the two localization values will be displayed.

Note: Assure that every internationalization key is unique. Otherwise, errors will occur due to name collisions.

Form Renaming

When renaming forms, certain forms may need to be named using information directly from the form. For example, adverse event terms such as headache and drowsiness could be in the title of the form to easily identify the adverse events in the form summary. To configure the name for internationalization, the plus-operator must be used to piece the form name together.

Assume that the clinical trial has the Fountayn project ID, XXX09100. In English, the form should be titled, “[Adverse Event term], starting at: [start date] .” Also assume that the adverse event term is designated by the property name, aeterm, and that the start date is designated by the property name, aestdt.

Add i18n keys to the forms

In the following example, the i18n key is added to the ‘Rename To’ column of the FormTypes worksheet

Add Localization Properties

In order for the correct text to appear in the system, the i18n keys and the localization properties need to be added to the App Properties worksheet as shown in the following example.

Note: Assure that every internationalization key is unique. Otherwise, errors will occur due to name collisions.

Scripting

Scripts that display text in the system need to be internationalized with i18n keys and localization properties.

Assume that the clinical trial has the Fountayn project ID, XXX09100.

Add i18n keys to the script

The following script on the Scripts worksheet uses two i18n keys.

<script scriptId="before_consent">
  <body>
    <s:alert>
      <s:expression>
        <s:gte>
          <s:partialDatePath path=":value"/>
          <s:toPartialDate>
            <s:datePath path="icdc:value"/>
            <s:string value="dd[]-MMM[]-yyyy[]"/>
            </s:toPartialDate>
        </s:gte>
      </s:expression>
      <s:correction>
        <s:string value="optional"/>
      </s:correction>
      <s:text>
        <s:concat>
          <s:string value="@@XXX09100.cannot.be.before.ic "/>
          <s:toString>
            <s:datePath path="icdc:value"/>
            <s:string value="dd-MMM-yyyy"/>
          </s:toString>
          <s:string value=". @@XXX09100.Please.verify."/>
        </s:concat>
      </s:text>
    </s:alert>
  </body>
  <target typeId="visitdc"/>
</script>

Add Localization Properties

In order for the correct text to appear in the system, the i18n keys and the localization properties need to be added to the App Properties worksheet as shown in the following example.

Note: Assure that every internationalization key is unique. Otherwise, errors will occur due to name collisions.

Translate All Localization Properties

Compile List of Localization Properties

After decompiling the file and adding internationalization keys for special cases, the list of localization properties in the App Properties worksheet is complete. All these properties need to be extracted into a list to prepare for translation.

Use Excel’s auto filter (Data > Filter > Auto Filter) to select the Localization Properties.

Translate the Localization Properties List

In general, the localization for any additional language requires localization/translation experts. Provide them with the complete list of localization properties.

Merge Translated List Into Data Architect File

After translation, the localization properties can be added to the App Properties worksheet of the Data Architect file. After performing some tests, the study is ready to be viewed in all of the languages configured.

Keys and Properties

Internationalization Keys (I18n Keys)

An i18n key is written in the form, ‘@@[i18nPluginID].’ followed by a sequence of letters, digits and dots. The i18nPluginID depends on the ID configured for the study.

Assume that the clinical trial has the Fountayn project ID, XXX09100, for the following examples.

Examples

• @@XXX09100.roleId.Coordinator
• @@XXX09100.eSubmission.PDF.Export
• @@XXX09100.Value.entered.must.be.a.decimal.number…Please.correct.

Invalid i18n Keys

• @@XXX09100roleId.Coordinator — the dot after the plug-in ID is missing
• @@XXX09100.eSubmission_PDF_Export — the underscore character is an invalid character

Localization Properties (l10n Properties)

Localization properties are used to provide localized terms for the i18n keys. Localization properties are written in the form, ‘[i18n key].’ followed by the language code. The value of the property is the term that should replace the i18n key in the system.

Assume that the clinical trial has the Fountayn project ID, XXX09100, for the following examples.

Examples

The following table demonstrates how the internationalization keys and localization properties work together for a multi-lingual trial.

Tips and Tricks

Test the Clinical Trial

When manually adding i18n keys and l10n properties, tests should be performed to assure that:

• No typos or other errors have occurred in relation to the i18n keys and l10n properties
• The application supports localization for all the added properties

I18n Keys Ending With a Dot

For text statements ending with a period (i.e. a dot), the i18n key can end with a dot. When adding the localization property name, an additional dot is required before the language code as shown in the following example.

Excel and the ‘ as Leading Character

Data Architect files are Excel files. When the first character in a cell is a single quote, Excel interprets this as an instruction for Excel to handle the following characters as text.

Example: Typing ‘Hello’ will result in a cell with the text, Hello’. Add two single quotes by typing ”Hello’ will result in a cell with the text, ‘Hello’.

Excel and the @ as Leading Character

Usually, Excel assumes that a leading @ will specify a formula, which should not be the case when specifying a localization property name. In order to specify that the localization property name is a string, add a single quote to the beginning of the cell text. Excel interprets this single quote to mean that the text following the single quote is plain text.

Example: To add @@XX12345.key to a cell, type ‘@@XXX12345.key

Inconsistent String Values – Generation of I18n keys

In certain cases, the automatic internationalization process that occurs during decompiling can result in errors that need to be resolved manually. This can happen when  two i18n keys are created with the same name. During the compilation of the Data Architect file, the following error may occur:

Error: FormFlow. Line 5: Inconsistent local string value. Key: “@@XXX01900.Number..en”, New: “Number:”, Old: “Number#”

This means that the internationalization key, @@XXX01900.Number., was already mapped to the term, “Number#” but is now being mapped to the term, “Number:” which is causing a name collision. Since both terms contain special characters that are not used in i18n keys, they both map to the same i18n key.

To address this issue, first assure that the terms are correct. If both terms should be used in the system, a new i18n key and localization property need to be defined manually as described when handling special cases.

Need more help?

Please visit the Fountayn Contact Information page.