Академический Документы
Профессиональный Документы
Культура Документы
COM
Application Express
Developing & Publishing Multilanguage Applications
APEXNINJAS.COM 2/24/2011
Document history Date 24/02/2011 Author George Bara Version 1.0 Modifications Created this document
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
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.
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
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.
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!)
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]
: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):
We will now translate and publish the application: Go to Application Builder -> Your Application -> Shared Components -> Globalization -> Translate Application Follow the 6 steps:
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
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: 11
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 translate also APEX text messages, such as the Help text from the Search Bar action menu for the interactive grid.
13
14
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...
15
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.
16