Service Company Tutorial, Chapter 4: Implementing Internationalization Infrastructure

This chapter of the tutorial describes how to implement the internationalization infrastructure of the application before starting to build the application UI. You can access the previous chapters of the tutorial through the following links;

You can also install the application in your local Formspider installation following the installation guide below:
SRDEMO Installation Guide

It contains the following topics:

  • Creating languages
  • Creating a multilingual key
    • Static multilingual value
    • Dynamic (parametic) multilingual value
  • Using a multilingual key
    • Design-time
    • Run-time
  • Improving internationalization performance

Implementing Internationalization Infrastructure

As a business goal, the application should be implemented with English and Italian multilingual support. To achieve this, you will benefit from Formspider Languages and Multilingual Keys.

Creating Languages

Open Formspider IDE. To create the necessary languages, perform the following steps:

  1. Expand the “Miscellaneous” accordion.
  2. Expand “Internationalization” node from the tree and double click “Languages” to open the “Languages” dialog.

    Double click “Languages”

  3. Click the “+” button to create a new language. Enter “English” as the “Name”, “EN” as the “Language Code” and “en” as “Local Code”. Leave “Decimal Separator” and “Thousand Separator” blank, meaning that the NLS_NUMERIC_CHARACTERS parameter of your database will be used as the decimal and thousand separator of the application.
  4. Click the “+” button again to create a second language. Enter “Italian” as the “Name”, “IT” as the “Language Code” and “it” as “Local Code”. Leave “Decimal Separator” and “Thousand Separator” blank again.
  5. Select “English” language as “Default” and click “OK”.

    Creating “English” and “Italian” languages

Creating Multilingual Key-Value Pairs

After creating the languages, create the multilingual keys of the application. For each multilingual key, you should define a value equivalent in every language existing in the application. A multilingual value can be:

  • Static (Fixed): If the multilingual value doesn’t change during run-time (Example: Yes, No, Cancel…)
  • Dynamic (Parametric): If the multilingual value contains some parameters that should be set in run-time (Example: Are you sure you want to delete service request #XXX?)

Creating a Static Multilingual Key-Value Pair

  1. Expand the “Miscellaneous” accordion.
  2. Expand “Internationalization” node from the tree and double click “Multilingual Keys” to open the “Multilingual Keys” dialog.

    Double click “Multilingual Keys”

  3. Select “English” from the “Language” comboBox and click the “+” button to create a multilingual key. Enter “srdemo.yes” as “Key” and “Yes” as “Value” for the language “English”.

    Setting multilingual value in “English”

  4. Select “Italian” from the “Language” comboBox, you will see “srdemo.yes” key without any value since a value for the “Italian” language is not defined yet. Enter “Sì” as “Value” for the language “Italian”.

    Setting multilingual value in “Italian”

  5. Click “OK” to save the multilingual key.

Creating a Dynamic Multilingual Key-Value Pair

  1. Expand the “Miscellaneous” accordion.
  2. Expand “Internationalization” node from the tree and double click “Multilingual Keys” to open the “Multilingual Keys” dialog.
  3. Select “English” from the “Language” comboBox and click the “+” button to create a multilingual key. Enter “alert.deleteSR.message” as “Key” and “Are you sure you want to delete service request #{0}?” as “Value” for the language “English”. Note that “{0}” is a placeholder (reference) for your parameter. If the message contains multiple parameters, you can define more placeholders as {1}, {2}, …. {n}.

    Setting multilingual value with a placeholder in “English”

  4. Select “Italian” from the “Language” comboBox. Enter “Sei sicuro di voler cancellare ticket #{0}?” as the “Value” for the language “Italian”.

    Setting multilingual value with a placeholder in “Italian”

  5. Click “OK” to save the multilingual key.

Multilingual key creation is a part of the screen implementation process, you will create the necessary multilingual keys following the labels that will be displayed on a screen. Click here to download all multilingual keys and their values in English and in Italian.

Using a Multilingual Key

You may need to use a multilingual key and access to its value in design-time or in run-time.

  • Design-time: Generally, you may use a multilingual key in design-time if the label of a component rarely changes during run-time. Formspider introduces a special syntax to use a multilingual key in design-time, which can be generalized as #{lang.multilingualKey}. The part #{lang.} indicates that a multilingual value is expected and the multilingualKey is the name of the multilingual key that you have created through the “Multilingual Keys” dialog. For example, you can assign the key “srdemo.yes” created earlier to the label of a button component as follows:
    <button label=”#{lang.srdemo.yes}”/>
    

    Tip: You can concatenate a multilingual string with an other multilingual or non-multilingual string:

    <textLabel=”#{lang.srdemo.yes}:”/>
    

    In this case, when the current language is English, the label of the textLabel component will be displayed as “Yes:”

    <textLabel=”#{lang.srdemo.yes}:#{lang.srdemo.yes}”/>
    

    In this case, when the current language is English, the label of the textLabel component will be displayed as “Yes:Yes”


    You can find more details about how to use a multilingual key during the design-time in this tutorial.

  • Run-time: You can use api_application.getMultilingualValue API to retrieve the value of a multilingual key in the specified language. If a language is not specified, the API returns the value in the current language of the application.

    Retrieving Dynamic Multilingual Values

    Create a package named “srdemo_multilingual”. This package contains constant definitions and utility functions used with the purpose of implementing Formspider multilingual support mechanism. Create a function named “getParametrizedMLMessage”, this function returns the value of a parametric multilingual message after replacing the parameter place holders ({0}, {1}…) with the appropriate values.

    /**
    * Returns multilingual message with specified key by setting message parameters.
    * Parameter setting is done via a simple replace function.
    * @param in_messageKey_tx Key of the multilingual message
    * @param in_param1_tx     First parameter contained in multilingual message
    *
    * @returns Multilingual message with all parameters set
    */
    function getParametrizedMLMessage(in_messageKey_tx varchar2, in_param1_tx varchar2)
      return varchar2 is
      v_message_tx varchar2(4000);
    begin
      v_message_tx := api_application.getmultilingualvalue(in_messageKey_tx);
      -- replace parameter indexed as {0}
      v_message_tx := replace(v_message_tx,'{0}',in_param1_tx);
      return v_message_tx;
    end;
    

Tip: Improving Internationalization Performance
You can embed the multilingual key-value pairs into the Formspider middle-tier in order to improve the internationalization performance. To achieve this:

  1. Double click “Languages” to open the “Languages” dialog.
  2. Click “Download” to download the zipped file containing the multilingual keys directory for the application.

    Download the zipped file

  3. Unzip the downloaded file into “apps\SRDEMO\i18n\” folder in the Formspider middle tier installation.

Note: Once you implement the embedded utilization, you should download the new zip file and unzip it into “apps\SRDEMO\i18n\” every time you create, edit or delete a multilingual key.

Summary

In this chapter you continued to build your application by implementing the internationalization infrastructure following the business goals. You will widely use this infrastructure during your screen development to satisfy the multilingual support. You performed the following key tasks:

  • Created application languages
  • Created multilingual keys
  • Learned how to use multilingual keys
  • Discovered how to improving internationalization performance