14 Managing Application Globalization

About Language Identification

After you create an application, you specify a language preference on the Edit Globalization Attributes page. Then you select a primary application language and determine how the Application Express 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 Built in Application Builder

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

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's primary language, that is, in German. 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

After Oracle Application Express determines the language for an application, the Application Express engine alters the database language for a specific page request. It then looks for a translated application in the appropriate language. If the Application Express engine finds that language, it renders 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 Application Express 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 Application Builder, 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 Application Express 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 Application Express 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

The following procedure describes how to edit item attributes for items having the source type of Database Column.

To edit item attributes:

1. On the Workspace home page, click the Application Builder icon.

2. Select an application.

3. Select a page.

   The Page Definition appears.

4. Under Items, select the item name.

   The Edit Page Item page appears.

5. Under Name, make a selection from the Display As list.

6. Under source, select or enter a format mask.

Translating Applications for Multibyte Languages

If your application needs to run in several languages simultaneously (such as Chinese and Japanese), 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 database 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: Map the Target Language

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

To map the primary and target application language:

1. Navigate to the Translate Application page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Shared Components.

   4. Under Globalization, click Translate Application.

      The Translate Application page appears.

2. Click Map your primary language application to a translated application.

   The Application Mappings page appears.

3. Click Create.

4. On the Translation Application Mapping page:

   • Translation Application - Enter 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 into which you are translating.

   • Image Directory - Enter the directory where the images currently reside.

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

     Note that this language specific image directory is typically not needed for most translated applications.

5. Click Create.

Seeding Translatable Text

Seeding the translation copies all translatable text into the Translation Text repository. After you specify the language and seed the Translation Text, you can then generate and export an XLIFF file for translation.

The seeding process keeps your primary language application synchronized with the Translation Text repository. You should run the seed process any time your primary language application changes.

To seed translatable text:

1. Navigate to the Translate Application page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Shared Components.

   4. Under Globalization, click Translate Application.

      The Translate Application page appears.

2. On the Translate Application page, select Seed and export the translation text of your application into a translation file.

3. From Language Mapping, select the appropriate primary and target application ID map.

4. Click Seed Translatable Text.

   The XLIFF Export page appears.

   Note:

   XML Localization Interchange File Format (XLIFF) is an XML-based format for exchanging localization data. For information about the XLIFF or to view the XLIFF specification, see:

   http://www.xliff.org
   

Exporting Text to a Translation File

After you have seeded translatable text, a status box displays at the top of the XLIFF Export page indicating the total number of attributes that may require translation, including the number of:

• Existing updated attributes that may require translation

• New attributes that may require translation

• Purged attributes that no longer require translation

You can use this information to determine if you need to export translatable text for an entire application or just a specific page.

The XLIFF Export page is divided into two sections. Use the upper section of the page to export translatable text for an entire application (that is, all pages, lists of values, messages, and so on). Use the lower section to export translatable text for a specific page.

Uploading a Translated XLIFF Document

To upload a translated XLIFF document:

1. Navigate to the Translate Application page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Shared Components.

   4. Under Globalization, click Translate Application.

      The Translate Application page appears.

2. Click 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.

Applying an Uploaded XLIFF Document and Publishing an Application

After 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 Application Express 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 a translated XLIFF document and publish the application:

1. Navigate to the Translate Application page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Shared Components.

   4. Under Globalization, click Translate Application.

      The Translate Application page appears.

2. Click Apply your translation file and publish.

3. In the XLIFF Files repository, click the View icon next 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.

Deleting an Uploaded XLIFF Document

To delete an uploaded XLIFF document:

1. Navigate to the Translate Application page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Shared Components.

   4. Under Globalization, click Translate Application.

      The Translate Application page appears.

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 after 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 that you have correctly configured the application Globalization attributes.

Translating Messages Used in PL/SQL Procedures

If your application includes PL/SQL regions or PL/SQL processes or calls PL/SQL package, procedures, or functions, you may need to translate generated HTML. First, you define each message on the Translatable Messages page. Second, you use the APEX_LANG.MESSAGE API to translate the messages from PL/SQL stored procedures, functions, triggers, or packaged procedures and functions.

You create translatable messages on the Translate Messages page.

To define a new translation message:

1. Navigate to the Translate Application page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Shared Components.

   4. Under Globalization, click Text Messages.

2. On the Translate Messages page, click Create.

3. On Identify Text Message, specify the following:

   1. Name - Enter a name to identify the message.

   2. Language - Select the language for which the message would be used.

   3. Text - Enter 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
      

4. Click Create.

APEX_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;

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

Translating Messages Used Internally by Application Express

Oracle Application Express is translated into German, Spanish, French, Italian, Japanese, Korean, Brazilian Portuguese, Simplified Chinese, and Traditional Chinese. If your application uses a language that is not among the ten languages into which Oracle Application Express is translated, you need to translate messages displayed by the Application Express reporting engine.

For example, if you develop a Russian application and want to include report messages, such as pagination, in Russian, you need to translate the strings used in messages displayed in reports.

To translate messages:

1. Navigate to the Translate Application page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Shared Components.

   4. Under Globalization, click Text Messages.

2. On the Translate Messages page, click Create.

3. On Identify Text Message, specify the following:

   1. Name - Enter the name of each message that needs to be translated. See Table 14-3.

   2. Language - Select the language for which the message would be used.

   3. Text - Enter the text to be returned when the text message is called. If the English text message contains positional substitution values (for example, %0, %1), ensure that your defined message also contains the same named and number of positional substitution values.

4. Click Create.

Table 14-3 lists the internal messages that require translation.

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:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Shared Components.

   4. Under Globalization, click Translate Application.

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. Language - Select a target language.

   2. Translate From Text - Enter the source text to be translated.

   3. Translate To - Enter the translated text.

4. Click Create.

APEX_LANG.LANG API

Syntax

APEX_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 14-4 describes the parameters available in the APEX_LANG.LANG API.

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 APEX_LANG.LANG(color)
  FROM my_colors

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