apex multi language applications

Download APEX Multi Language Applications

Post on 08-Mar-2015

877 views

Category:

Documents

22 download

Embed Size (px)

TRANSCRIPT

APEXNINJAS.COM

Application ExpressDeveloping & Publishing Multilanguage ApplicationsAPEXNINJAS.COM 2/24/2011

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

Document history Date 24/02/2011 Author George Bara Version 1.0 Modifications Created this document

2

ContentsGlobalization 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

3

Globalization ConsiderationsAs 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 tutorialDescriptionAs said before, the actual globalization process can be started only after the application in the primary language is fully developed. 4

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 methodThe 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) 5

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

Step 2. Develop the language mechanism inside the applicationFor 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!)

6

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 7

: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):

8

Step 3. Translate and publish the applicationAt 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]

9

Translation Application: Choose and ID that doesnt 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:

10

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): Login Page Login Page After the translation it should look like this: Login Page Pagina autentificare After finishing translating the entire document, go to the next step: 11

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]

12

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