Multilanguage database applications using Oracle APEX

This article should give an overview and understanding of how the translation mechanism that is built-in to Oracle APEX works, and how you should handle it. There are lots of reasons for applications to be multilingual. If you have end-users that are located internationally, you will probably end up supporting many languages or at least the most widely used ones.

 

There is also a lot more to take into consideration when deploying your application in various languages, such as date- and number-formats or languages printed right-to-left.

 

If you need your data to also be multilingual, then you will need to take care of it in your data-model and your application code.

 

Oracle APEX handles translations as a copy of the main application. That means that for every language supported by the application, APEX internally creates a “Shadow Application”. These shadow applications aren’t listed in application builder, but they are exact copies of the main application and they exist in the APEX dictionary tables.

 

All code changes are done in the main application which is then rolled out to the translated shadow applications with the “seed” and “publish” operations. So whenever you need to roll out code-changes you need to seed and publish all translations.

 

The main step in understanding translations in Oracle APEX is to realize that there is always a copy of the full application (every page, every process, and every single line of code) for each language you want to support.

 

The following three steps are required to create the multilingual APEX applications:

  1. Prepare the application for the translation process
    2. Generate user-friendly navigation bar entries for switching languages
    3. Follow the translation process in globalization

 

 1. Prepare the application for translation process:

 

  • Go to shared components block of the main application.

 

 

  • Go to the globalization attributes under globalization menu and set the property ‘application language derived from’ to ‘item preference (use item containing preference)’.

 

 

APEX now knows that it can derive the language to show the page in from a special application item. But this item still has to be created.

 

Now in order to create an item for the preference, the following steps are required:

  • Go to shared components
  • Under application logic menu

 

 

 

  • Click on application items >  Create
  • Enter the name as FSP_LANGUAGE_PREFERENCE
  • Under Security select Checksum Required -Session Level
  • Click on Create Application Item

 

 

The item is called FSP_LANGUAGE_PREFERENCE, because APEX recognizes that name as an item reserved for application languages. When a page is rendered, APEX checks the FSP_LANGUAGE_PREFERENCE item to see in what language the page has to be shown.

 

Whenever the language is changed, the page has to be reloaded to show the result. To make this happen, we are going to add an application process that will handle the reloading of the page.

  • Return to shared components
  • Under application logic menu à click on application processes > Create
  • Enter the name as set_language
  • Set ‘process point’ as ‘On Load: Before Header (page template header)’
  • Click on Next

 

 

  • In the source block enter below PL/SQL code

 

begin
owa_util.redirect_url('f?p='||:APP_ID||':'||:APP_PAGE_ID||':'||:
APP_SESSION);
end;

 

  • Click on Next

  • Select condition type Request = Expression1
  • Enter LANG in Expression 1 text area (‘LANG’ all in upper case)
  • Click on Create Process to finish

 

Now our application is ready with the application process and with language-specific Item.

 

2. Generate user-friendly navigation bar entries for switching languages

Now give some user-friendly options in the application like user can change application language with one click, for that we need to create some navigation bar entries with language options.

The best place to create a language switch is a place that is visible at all times. In this case, we will use the navigation bar. Since this bar is in the header of our application, it is visible on all pages and ideal for our purposes.

Create navigation entries:

  • First, go to shared components
  • Under navigation find navigation bar list
  • Click on Navigation Bar List -> Desktop Navigation Bar -> Create Entry

 

 

  • Click on Create List Entry
  • List Entry Label: Enter the navigation bar name
  • Target type: page in this application
  • Page: &APP_PAGE_ID. (‘.’required)
  • Request: LANG
  • Set these items: FSP_LANGUAGE_PREFERENCE
  • With these values: en (language code)
  • Click on Create List Entry

 

 

Repeat same steps to create more navigation menu entries for required languages.

 

Now that we have a translatable application, we will have to create a translated version of the application in another language.

 

 

3. Follow the translation process in globalization

The translation workflow consists of a couple of steps, which may be repeated each time you roll out a new version of the application:

  • Go to shared components > Translate Application

 

Under the translate, one can see the below-mentioned flow of translation process.

 

 

a) Define application languages (map the primary and target application IDs)

  • Define application languages > Create
  • Enter the unique ID for translated application

(Tip: To avoid conflicts with other applications in the same workspace, we recommend you to extend the unique ID of the translated target application from the main application ID. For example, the ID of the main application is 105 assigned for the target applications as 10501, 10502, etc.)

 

  • Next select language to which you want to translate then finish with Create click

 

This will tell APEX the new language that is going to be used.

 

 

b) Seed translatable text (seed and export the text to a file for translation)

  • Go back to translate page and then click on seed translatable text
  • Check the translated application ID and then click on seed button

 

 

This will create entries in the APEX translation repository for every translatable text in the application. These entries will be used later to generate the XLIFF files.

One of the world’s most recognized standards in localization is the XLIFF format. XLIFF is the abbreviation for XML Localization Interchange File Format. As the name explains, it’s an XML standard and it has been adopted by Application Express as the format in which different language files can be exported from and imported into APEX applications.

 

c) Download XLIFF translation files

  • Again go back to translate page click on download XLIFF translation files
  • Select desired language from the list of languages

In this page one has two options to export XLIFF file: one can choose a page in the application or entire application

  • Click on Export XLIFF file for the application and save under your local directory (this XLIFF file contains XML data)

 

 

The XLIFF file has now been downloaded and is ready to be edited.

The quickest way to translate a lot of text is still using the XLIFF file. Because this is an international standard, an XLIFF file can be handled by any translation service.

 

d) Translate the text in the file (third party job)

But for now, let’s do some small changes in XLIFF file.

  • Open your downloaded XLIFF file for editing in your favorite text editor and change the text between tags <target> with the translation in the desired language from the text between the tags <source>

 

<source>Página Global – Escritorio</source>

<target>Global Page – Desktop</target>

<source>Inicio</source>

<target>Home</target>

Then save it and follow the next step.

 

e)Apply XLIFF translation files

  • Then click on Upload Files (upload the changed file)
  • Map the target application check it and click on Apply Checked Button

 

f) Publish the translated file

  • Go back to translate page and click on Publish translated applications
  • Check the files and click on Seed Button
  • Check the files and click on Publish Button

 

Now one can check the source and target language data in translation repository. For that again navigate to translate window then click on Translation Repository (Shared Components -> Globalization -> Translate Application -> Translation Repository). There one can edit and reset the target data.  (For that one just need to spend some more time).

Now the application is available in two languages for the user.

 

 

Twitter
LinkedIn
Evolution, innovation and transformation
3 expertise + 42 specializations endorsed by Oracle
Our value proposition
100% Oracle posts
Follow our day-to-day activities