APEXNINJAS.COM

Application Express Developing & Publishing Multilanguage

Applications

APEXNINJAS.COM

2/24/2011

This is a guide on how to develop Multilanguage applications in APEX 3.0 versions

2

Document history

Date Author Version Modifications

24/02/2011 George Bara 1.0 Created this document

3

Contents Globalization Considerations ................................................................................................................... 4

Apex globalization tutorial ....................................................................................................................... 4

Description .......................................................................................................................................... 4

Step 1. Choosing a translation method ................................................................................................ 5

Step 2. Develop the language mechanism inside the application.......................................................... 6

Design a language switch button (for 2 language version of the application) .................................... 6

Create a hidden page item to store the language code .................................................................... 7

Create an application level process to handle the submit ................................................................. 7

Step 3. Translate and publish the application ....................................................................................... 9

Step 1. Map your primary language to a translated application ........................................................ 9

Step 2. Seed and export the translation text … ............................................................................... 11

Step 3. Translate the text in the exporter XLIFF file ........................................................................ 11

Step 4. Apply your translation file and publish ............................................................................... 12

Step 5. Optionaly translate text messages ...................................................................................... 13

Final considerations ............................................................................................................................... 16

4

Globalization Considerations As APEX is a development tool mainly oriented for frontend web-based applications, the globalization

issue is an important one. The development of an APEX Multilanguage application should be

considered from the first stages of the application design, as the globalization tools offered by

Application Express do not allow a great deal of flexibility and, if used incorrectly, can result in

disastrous results.

The following main principles must be followed when designing an APEX Multilanguage application:

1. Choose a primary language for you application, the language you will develop the application

into. For example, English.

2. Design the application completely, meaning that you will work only on the primary language

application all the way through the standard development stages (develop, user acceptance

tests, live tests). This must be done because the translated version of the application (for

example, the Romanian version) is independent from the main one, and will require rebuilding

it completely, if any change is done in the primary language application.

3. Make sure to develop the main application keeping in mind that you will translate it afterwards.

Add the language switch object, if needed, choose the desired globalization method and so on.

4. After publishing the applications in the other languages, keep in mind that any further

modifications can done only on the primary language application and a complete rebuild of

language dictionary and application is required if something changes.

5. Always remember that APEX is not so well documented. Never try anything that has not been

done before by other APEX developers! Keep yourself up to date with any new “tricks” or

features on the Oracle official forums, the APEX section.

This document applies to APEX 3.x versions. It is not clear yet if it applies also to APEX 4.0.

Apex globalization tutorial

Description As said before, the actual globalization process can be started only after the application in the primary

language is fully developed.

5

For our example, we have an application developed in English, that will be translated into Romanian.

The translated application will be invisible in the Application Builder section, as it is just a derived

application and cannot be modified directly. For example, if our main application is 140, the Romanian

version can be 141, the Dutch one 142 and so on…

Step 1. Choosing a translation method The translated application will be derived from the primary language application, as stated before. The

3 methods are:

- Browser

- Application preference

- Item preference

To choose a method, go to: Application Builder -> Application 140 (we will use this App Id from now

on) -> Shared Components -> Edit globalization attributes , field Application Language Derived from

The options are:

- No NLS (application will not be translated)

- Use application primary language (obvious)

- Browser (the choosing of the language will be dependant of the language setting of the

browser!)

- Application preference (recommended, will use an application setting through all the

application pages)

- Item preference (will use an application level item called FSP_LANGUAGE_PREFERENCE, that will

be set manually with a value and will be used explicitly by all pages, not recommended)

6

In our example, we will use the APPLICATION PREFERENCE from now on.

Step 2. Develop the language mechanism inside the application For the APPLICATION PREFERENCE translation method, we can use the following approach:

Design a language switch button (for 2 language version of the application)

We will add the “switch language” on the login page. This button will switch between the languages

“Romana” and “English” and is intended to change its label text depending on the current language:

To design it, follow these steps:

Go to Application Builder -> Your application -> [Login Page] -> [Button region] -> Add

Name: ROMANA

Not conditional

URL Redirect to same page [Login Page]

Request: LANG(IMPORTANT!)

7

Create a hidden page item to store the language code

We will next create an item to store the language code for the different language switches. For our case

we will use ro and en. Note that this language codes are standard and should be verified in the APEX

standard documentation.

Go to Application Builder -> You Application -> [Item area] -> Add item

Create an item called P1000000_LANG, hidden and protected

Create an application level process to handle the submit

Goto Application Builder -> Your Application -> Shared Components -> Application Processes ->

[CREATE]

Make the process loading point: On Load (Before Header)

Enter the following Process Text:

BEGIN

IF NVL(:P1000000_LANG,'en')='ro' THEN

8

:P1000000_LANG :='en';

ELSE

:P1000000_LANG :='ro';

END IF;

APEX_UTIL.SET_PREFERENCE ('FSP_LANGUAGE_PREFERENCE',:P1000000_LANG,:APP_USER);

owa_util.redirect_url('f?p='||:APP_ID||':'||:APP_PAGE_ID||':'||:SESSION);

END;

This will set the value of the hidden item :P1000000_LANG to the language code (en or ro), will set the

language preference with this code

APEX_UTIL.SET_PREFERENCE('FSP_LANGUAGE_PREFERENCE',:P1000000_LANG,:APP_USER);

And will refresh the page, so that it will be displayed in the desired language.

Make the process conditional, so that it will trigger only when page is refreshed using the language

switch button (“Romana”):

9

Step 3. Translate and publish the application

At this point, we should have:

- The application in the primary language (English) developed

- The language switch button developed and the underlying mechanism (Steps 1 and 2)

We will now translate and publish the application:

Go to Application Builder -> Your Application -> Shared Components -> Globalization -> Translate

Application

Follow the 6 steps:

Step 1. Map your primary language to a translated application

Click [Create]

10

Translation Application: Choose and ID that doesn’t end with 0 (zero). Most suitable, as in the image

above, if the main application is 140, choose 141,

Language code: choose Romanian(ro)

Click [Create]. This will create the mapping:

11

Step 2. Seed and export the translation text …

Language Mapping: choose the mapping created in Step 1.

Click [Seed Translatable Text]

Application: the mapping previously created

Click [Export …] and save the XLIFF file.

Step 3. Translate the text in the exporter XLIFF file

Unfortunately, this can be done only manually or using an external XML editing tool, suggested with

dictionary features.

The XLIFF file has a tag structure like this (example with one attribute):

<source>Login Page</source>

<target>Login Page</target>

After the translation it should look like this:

<source>Login Page</source>

<target>Pagina autentificare</target>

After finishing translating the entire document, go to the next step:

12

Step 4. Apply your translation file and publish

Click [Upload XLIFF]

Give it a suggestive title (you can have multiple uploaded XLIFF translation files!), upload the translated

XLIFF file and click [Upload XLIFF File]

13

Click [Apply …]. The translation file will be applied, application 141 will be created and published. If all is

successful, you can test the result:

Run the application. Switch between languages using the previously created button:

Step 5. Optionaly translate text messages

Application Builder -> Your Application -> Shared Components -> Globalization -> Text Messages

You can translate also APEX text messages, such as the Help text from the Search Bar action menu for

the interactive grid.

14

15

Notice that a portion of the text message is translated into Romanian.

That portion of text is actually stored by Apex as a Text Message, with the name

APEXIR_HELP_SEARCH_BAR . A translation for the message can be added for the Romanian language:

The full list with the Text Messages is available in the APEX help system at Home > Managing

Application Global... > Translating Messages > Translating Messages Used I...

16

Final considerations After going through the tutorial, you will have an application that is available in 2 languages, English and

Romanian. These important issues must be kept in mind:

- Adding a new object in the primary application (140), will not automatic add it into the

translated derived one (141). You will have to translate and publish 141 again.

- Exporting application 140 will not export also 141, the translated application. You can export

separately 141, but it will not be usable.

- Importing an application with a derived language application, will not import also the translated

application. After the import, you will have to publish the translated application again. So, no

automated mechanism for moving Multilanguage application from an environment to another

exists.

- It is recommended that you do not use Multilanguage APEX applications in production

environments is you intend to change the applications often, because you will have to republish

them every time.

Deploying Multilanguage Applications in Runtime Mode: impossible? As you probably know, when installing APEX you can choose between installing in full development

mode and in runtime mode. You can do this by running the apexins.sql script or the apexrtins.sql script.

The primary difference is that in run time mode, the users cannot edit the applications, only run them.

In runtime mode, you do not have access to the Application Express Login page, the Application Express

development tool, Application builder and so on. Every modification or application deploy will be done

by connecting to the database (as sys) and manually running the import scripts (previously exported

from an APEX instance available in development mode) in sqlplus. Using the APEX API is also an option

when working with a runtime mode instance.

Unfortunately, it seems that deploying Multilanguage applications in a runtime environment is not

possible. Publishing of the translated applications cannot be done by simply exporting the whole

Multilanguage application from the development instance and running the script in sqlplus, in the

runtime instance.

This drawback is not clearly documented. There may be a way to publish multilanguage applications in

runtime environments, but it has not been made public and the apexninjas.com team has not figured

out a way to do it, until the time of this whitepaper’s creation.

Maybe publishing this whitepaper will produce some feedback to resolve this issue.