15 Managing Oracle HTML DB Globalization

About Language Identification

After you create an application, you specify a language preference on the Edit Application Attributes page. Under Globalization, you select a primary application language and select how the HTML DB engine determines the application language. You can specify to have the application language based on the user's browser language preference, an application preference, or an item preference.

Rules for Translating Applications in Oracle HTML DB

When using translated applications in Oracle HTML DB, use the following rules to determine which translated version to use:

• Look for an exact match between the user language preference and the language code of the translated application

• Look for a truncated match. That is, see if the language and locale exist. For example, if the user language preference is en-us and the translated version of en-us does not exist, look for a translated application that has the language code en

• Use the primary application

For example, suppose you create an application with the primary language of German, de, and you create a translated version of the application with a language code of en-us. Users accessing this application with a browser language of en-us execute the English en-us version of the application. Users accessing the application with a browser language of en-gb view the application in the application primary language. In this example, these users see the application in German, which is the application's primary language. For this example, you should create the translated English version using language code en to encompass all variations of en.

How Translated Applications Are Rendered

Once Oracle HTML DB determines the language for an application, the HTML DB engine alters the database language for a specific page request. It then looks for a translated application in the appropriate language. If the HTML DB engine finds that language, it render the application using that definition. Otherwise, it renders the application in the base (or primary) application language.

Note that the text that displays within an application is not translated on the fly. Oracle HTML DB dynamically collects page attributes from either a base language application definition or an alternative application definition.

About Translatable Components

When you build an application in Oracle HTML DB, you define a large number of declarative attributes such as field labels, region headings, page header text, and so on. Using the steps described in this section, you can make all the application definition attributes within your application translatable.

Using Format Masks for Items

The HTML DB engine applies globalization settings for each rendered page. This default behavior can impact the display of certain items such as numbers and dates.

For example, suppose your application determines the application language based on the user's browser language preference. If the HTML DB engine determines the users's browser language preference is French, it displays dates and numbers in a format that conforms to French standards. You can override this default behavior and explicitly control how items display by applying a format mask. You apply a format mask by making a selection from the Display As list:

• When you create the item

• After you create the item by editing the item attributes

To edit item attributes:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. Select a page.

   The Page Definition appears.

5. Under Items, select the item name.

   The Edit Page Item page appears.

6. Under Identification, make a select from the Display As list.

Translating Applications for Multibyte Languages

If your application needs to run in several languages (such as Chinese or Japanese) simultaneously, consider configuring your database with a character set to support all of the languages. The same character set has to be configured in the corresponding data access descriptor (DAD) in mod_plsql. UTF8 and AL32UTF8 are the character sets you can use to support almost all languages around the world.

Step 1: Navigate to the Translate Application Page

You perform the translation process on the Translate Application page.

To navigate to the Translate Application page:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. Click Shared Components.

5. Under Globalization, select Translation Services.

   The Translate Application page appears.

Step 2: Map Primary and Target Application IDs

The first step in translating an application is to map the primary and target application IDs. The primary application is the application to be translated. The target application is the resulting translated application.

To map the primary and target application IDs:

1. Navigate to the Translate Application page. See "Step 1: Navigate to the Translate Application Page".

2. On the Translate Application page, select Map your primary language application to a translated application ID.

   The Application Mappings page appears.

3. Click Create.

4. On the Translation Application Mapping page:

   • Translation Application - Type a numeric application ID to identify the target application. The translated application ID must be an integer and cannot end in zero.

   • Translation Application Language Code - Select the language you are translating to.

   • Image Directory - Enter the directory where images will be obtained.

     This attribute determines the virtual path for translated images. For example, if your primary language application had an image prefix of '/images/', you could define additional virtual directories for other languages such as '/images/de/' for German or '/images/es/' for Spanish.

5. Click Create.

Step 3: Seed and Export Text to a Translation File

The second step is to seed the translation table and then export the translation text to a translation file.

Topics in this section include:

• Seeding Translatable Text

• Exporting Text to a Translation File

Step 4: Translate the XLIFF File

After you export a translatable file to XLIFF format, you can translate it into the appropriate languages. Since XLIFF is an open standard XML file for exchanging translation, most translation vendors should support it. Oracle HTML DB only supports XLIFF files encoded in UTF-8 character sets. In other words, it exports XLIFF files for translation in UTF-8 and assumes that the translated XLIFF files will be in the same character set.

Translation is a time-consuming task. Oracle HTML DB supports incremental translation so that application development can be done in parallel with the translation. A XLIFF file can be translated and uploaded to Oracle HTML DB even when only part of the XLIFF file is translated. For strings that have no translation in the corresponding translated application, Oracle HTML DB uses the corresponding ones in the primary language.

http://www.xliff.org

Step 5: Upload and Publish a Translated XLIFF Document

Once your XLIFF document has been translated, the next step is to upload it back into Oracle HTML DB.

To upload a translated XLIFF document:

1. Navigate to the Translate Application page. See "Step 1: Navigate to the Translate Application Page".

2. On the Translate Application page, select Apply your translation file and publish.

3. Click Upload XLIFF.

4. On the XLIFF Upload page:

   1. Specify a title

   2. Enter a description

   3. Click Browse and locate the file to be uploaded

   4. Click Upload XLIFF File

   The uploaded document appears in the XLIFF Files repository.

Once you upload an XLIFF document, the next step is to apply the XLIFF document and then publish the translated application. When you apply an XLIFF document, the HTML DB engine parses the file and then updates the translation tables with the new translatable text.

Publishing your application creates a copy of the base language application, substituting the translated text strings from your translations table. This published application can then be used to render your application in alternate languages.

Remember that in order to run an application in an alternative language, you need to run it with globalization settings that will cause an alternative language version to display. For example, if the language is derived from the browser language, you must set the browser language to the same language as the translated application.

To apply and publish a translated XLIFF document:

1. Navigate to the Translate Application page. See "Step 1: Navigate to the Translate Application Page".

2. On the Translate Application page, select Apply your translation file and publish.

3. In the XLIFF Files repository, click the View icon adjacent to the document you want to publish.

4. From Apply to, select the appropriate primary and target application ID map.

5. Click Apply XLIFF Translation File.

6. Click Publish Application.

To delete an uploaded XLIFF document:

1. Navigate to the Translate Application page. See "Step 1: Navigate to the Translate Application Page".

2. On the Translate Application page, select Apply your translation file and publish.

3. In the XLIFF Files repository, select the check box to the left of the document title.

4. Click Delete Checked.

You should verify the existence of the translated application once it is published. Translated applications do not display in the Available Applications list on the Application Builder home page. Instead, use the Application Navigate list on the left side of the page.

Note that in order for a translated application to appear in Application Builder, you need to make sure the you have correctly configured the application Globalization attributes.

Defining Translatable Messages

You create translatable messages on the Translate Messages page.

To define a new translation message:

1. Navigate to the Translate Application page. See "Step 1: Navigate to the Translate Application Page".

2. On the Translate Application page, select Optionally translate messages which are used by PL/SQL procedures and functions.

3. On the Translate Messages page, click Create.

4. On the Identify Text Message page:

   1. In Name, type a name to identify the text message

   2. In Language, select the language for which the message would be used

   3. In text, type the text to be returned when the text message is called.

      For example, you could define the message GREETING_MSG in English as:

      Good morning %0
      
      

      Or, you could define the message GREETING_MSG in German as:

      Guten Tag %0
      
      

5. Click Create.

HTMLDB_LANG.MESSAGE API

Use the HTMLDB_LANG.MESSAGE API to translate text strings (or messages) generated from PL/SQL stored procedures, functions, triggers, packaged procedures and functions.

Syntax

HTMLDB_LANG.MESSAGE (
    p_name    IN    VARCHAR2 DEFAULT NULL,
    p0        IN    VARCHAR2 DEFAULT NULL,
    p1        IN    VARCHAR2 DEFAULT NULL,
    p2        IN    VARCHAR2 DEFAULT NULL,
    ...
    p9        IN    VARCHAR2 DEFAULT NULL,
    p_lang    IN    VARCHAR2 DEFAULT NULL)
    RETURN VARCHAR2;

Parameters

Table 15-2 describes the parameters available in the HTMLDB_LANG.MESSAGE.

Example

The following example assumes you have defined a message called GREETING_MSG in your application in English as Good morning%0 and in German as Guten Tag%1. The following example demonstrates how you could invoke this message from PL/SQL:

BEGIN
    --
    -- Print the greeting
    --
    HTMLDB_LANG.MESSAGE('GREETING_MSG', V('APP_USER'));
END;

How p_lang attribute is defined depends on how the HTML DB engine derives the Application Primary Language. For example, if you are running the application in German and the previous call is made HTMLDB_LANG.MESSAGE, the HTML DB engine first looks for a message called GREETING_MSG with a LANG_CODE of de. If it does not find anything, then it will revert to the Application Primary Language attribute. If it still does not find anything, the HTML DB engine looks for a message by this name with a language code of en-us.

Defining a Dynamic Translation

You define dynamic translations on the Dynamic Translations page. A dynamic translation consists of a "translate-from" language string, a language code, and a "translate-to" string.

To define a dynamic translation:

1. Navigate to the Translate Application page. See "Step 1: Navigate to the Translate Application Page".

2. On the Translate Application page, select Optionally identify any data that needs to be dynamically translated to support SQL based lists of values.

3. On the Dynamic Translations page, click Create and specify the following:

   1. In Language, select a target language

   2. In Translate From Text, type the source text to be translated

   3. In Translate To, type the translated text

4. Click Create.

HTMLDB_LANG.LANG API

Syntax

HTMLDB_LANG.LANG (
    p_primary_text_string    IN    VARCHAR2 DEFAULT NULL,
    p0                       IN    VARCHAR2 DEFAULT NULL,
    p1                       IN    VARCHAR2 DEFAULT NULL,
    p2                       IN    VARCHAR2 DEFAULT NULL,
    ...
    p9                       IN    VARCHAR2 DEFAULT NULL,
    p_primary_language       IN    VARCHAR2 DEFAULT NULL)
    RETURN VARCHAR2;

Parameters

Table 15-3 describes the parameters available in the HTMLDB_LANG.LANG.

Example

Suppose you have a table that defines all primary colors. You could define a dynamic message for each color and then apply the LANG function to the defined values in a query. For example:

SELECT HTMLDB_LANG.LANG(color)
  FROM my_colors

For example, suppose you were running the application in German andRED was a value for the color column in my_colors table. If you defined the German word for red, the previous example would return ROT.