Previous Next JavaScript must be enabled to correctly display this content

## 22.1 Understanding Application Translation and Globalization Support

Learn about developing APEX applications that can run concurrently in different languages.

A single Oracle Database instance and Oracle APEX can support multiple database sessions customized to support different languages.

- Overview of the Translation Process
  Learn about translating an application built in App Builder.
- About Language Identification
  Learn how the APEX engine determines the application language.
- About the Rules for Translating Applications
  Learn about rules for translating applications.
- How Translated Applications Are Rendered
  Learn about how APEX renders translated applications.
- Making Application Attributes Translatable
  Learn about best practices to make application attributes within your application translatable.

Parent topic: Managing Application Globalization

### 22.1.1 Overview of the Translation Process

Learn about translating an application built in App Builder.

In general, translating an application built in App Builder involves the following steps:

- Before You Begin: Enable Application Translation and Configure Attributes – Configure Globalization attributes and enable application translation. Key attributes include: Application Primary Language, Translate Application switch, and Translate Method.
- If the Translate Method is Application-Based:

  - Step 1: Define Application Languages - Create a mapping which identifies the target primary and target application language.

  - Step 2: Seed and Download to a Translation File - Seed the translation table and then export the translation text to a translation file. Seeding the translation copies all translatable text into the Translation Text repository. After you specify the language and seed the Translation Text, you generate and export an XLIFF file for translation.

  - Step 3: Translate the XLIFF File - Download the XLIFF files for translation or manually edit the translation repository.

  - Step 4: Upload and Apply a Translated XLIFF Document - Upload XLIFF files with translated text and apply translations to the Translation Text repository.

  - Step 5: Publish the Application - Make the translated application available to users.

- If the Translate Method is Text-Message Based:

  - Step 1 - Convert to Text Messages – Convert all translatable text in the application to text messages using Convert to Text Wizard.

  - Step 2: Define Application Languages - Choose a language to synchronize primary language text messages to the chosen language.
  - Step 3: Translate Text Messages - Download text messages for a single language or all chosen languages in either XLIFF or CSV format for translation. Alternatively, manually edit text messages for translation languages.
  - Step 4: Upload Translated File – Update text messages with translated text from a single language file or multiple language ZIP file.

To learn more, see Understanding the Translation Process.

Parent topic: Understanding Application Translation and Globalization Support

### 22.1.2 About Language Identification

Learn how the APEX engine determines the application language.

After you create an application, you specify a language preference by editing the Application Primary Language attribute. Globalization attributes control how the how the APEX engine determines the application language. The application primary language can be static, derived from the Web browser language, or determined from a user preference or item.

To learn more, see Before You Begin: Configure Globalization Attributes.

Parent topic: Understanding Application Translation and Globalization Support

### 22.1.3 About the Rules for Translating Applications

Learn about rules for translating applications.

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

Parent topic: Understanding Application Translation and Globalization Support

### 22.1.4 How Translated Applications Are Rendered

Learn about how APEX renders translated applications.

After APEX determines the language for an application, the APEX engine alters the database language for a specific page request. What happens next depends upon the selected Translation Method.

For an Application-Based Translation

APEX looks for a translated application in the appropriate language. If the APEX engine finds that language, it renders the application using that definition. Otherwise, it renders the application in the base (or primary) application language.

For an Text-Message Based Translation

The APEX engine renders the same application for all languages using text messages in the set language. If a text message does not exist for a language, APEX defaults to the text message defined in the primary language.

Related Topics

- About Dynamic Translation Text Strings
- Translating Data That Supports List of Values

Parent topic: Understanding Application Translation and Globalization Support

### 22.1.5 Making Application Attributes Translatable

Learn about best practices to make application attributes within your application translatable.

When you build an application in App Builder, you define a large number of declarative attributes such as field labels, region headings, page header text, and so on.

- About Shortcuts that Support Translatable Messages
  Learn about shortcuts that support translatable messages.
- About Messages
  Learn about messages.
- About Dynamic Translation Text Strings
  Learn about dynamic translation text strings.
- Marking a Region as Not Translatable
  Learn about marking a region as not translatable.
- Identifying a Template as Translatable
  Learn how to identify a template as translatable.

Parent topic: Understanding Application Translation and Globalization Support

#### 22.1.5.1 About Shortcuts that Support Translatable Messages

Learn about shortcuts that support translatable messages.

App Builder includes two shortcut types that enable you to reference translatable messages:

- Message. Use this shortcut to reference a translatable message at runtime. Note that the name of the shortcut must match the corresponding message name. At runtime, the name of the shortcut expands to the text of the translatable message for the current language.

- Message with JavaScript Escaped Single Quotes. Use this shortcut to reference a shortcut inside of a JavaScript literal string and reference a translatable message at runtime. This shortcut defines a text string. When the shortcut is referenced, it escapes the single quotation marks required for JavaScript.

To learn more, see Using Shortcuts.

Parent topic: Making Application Attributes Translatable

#### 22.1.5.2 About Messages

Learn about messages.

If your application includes PL/SQL regions or PL/SQL processes, you must translate any generated HTML or text. You may also need to translate messages used in reports if your application uses a language that is not one of the ten languages into which APEX is translated.

To learn more, see Translating Messages.

Parent topic: Making Application Attributes Translatable

#### 22.1.5.3 About Dynamic Translation Text Strings

Learn about dynamic translation text strings.

Dynamic translations are used for database data that must be translated at runtime. For example, you might use a dynamic translation to translate a list of values based on a database query. A dynamic translation consists of a translate-from language string, a language code, and a translate-to string. You can also use the `APEX_LANG.LANG` API to retrieve dynamic translations programmatically.

To learn more, see Translating Data That Supports List of Values.

Parent topic: Making Application Attributes Translatable

#### 22.1.5.4 Marking a Region as Not Translatable

Learn about marking a region as not translatable.

By default, page region titles are included in the generated translation file. However, you can mark a region title as not translatable.

To mark a region title as not translatable:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In the Rendering tab, select the region.
   The Property Editor displays the region attributes. Attributes are organized in groups.
3. Find and expand the Advanced group.
4. For For Exclude Title from Translation, select On to exclude this title from translation. This attribute has no effect, except when translating the application into another language.
5. Click Save.

Parent topic: Making Application Attributes Translatable

#### 22.1.5.5 Identifying a Template as Translatable

Learn how to identify a template as translatable.

By default, templates are not translatable, and therefore are not included in the generated translation file. Generally, templates do not and should not contain translatable text. However, if you must mark a template as translatable, select the Translatable checkbox on the Edit Template page.

To identify a template as translatable:

1. On the Workspace home page, click the App Builder icon.
2. Select an application.
3. On the Application home page, click Shared Components.
4. Under User Interface, select Templates.
   The Templates page appears.
5. Select a template.
6. Under Name, select Translatable.
   You can include translatable text at the application level by defining the translatable text using static substitution strings. Because application-level attributes are translated, any text defined as a static substitution string is included in the generated translation file.

Related Topics

- Creating Custom Themes
- Substitutions

Parent topic: Making Application Attributes Translatable