Oracle ADF: ViewController Strings l10n Part 1

Hello all. For those of you who are using Oracle ADF or ADF Essentials and want to add language support to your applications, this post will give you an idea of the features that JDeveloper offers in order to accomplish this requirement and some best practices I have discovered when working with localization (i10n) (only the text translation part) on the ViewController  project of a Fusion Web application (ADF). It is important to note that this post is about the ViewController side of the application, the Model side works quiet different and will be addressed in another post.

What you need
JDeveloper 11gR2 (11.1.2.3.0) or superior.
Glassfish 3.1 or superior.

Configuration
After creating a Fusion Web Application (New->Applications->Fusion Web Application ADF), JDeveloper generates two projects: one for the model and another  for the view controller. Do the following in order to configure your ViewController project:

Right click on the project and select Project Properties:

A dialog opens with different properties for the project. At the left you can see the categories of the properties, select the one called ReIf you want to let the user select the language he/she wants, then you have to create a session managed bean with a language property and your source Bundle:

From the above image we can note the following:

• Select One Bundle Per Project radio button. This is a common configuration in most projects. It allows you to have one file for the whole project.
• According to your company standard you may have a long package structure like the one showed in the image.
• You can select Properties Bundle from the combo box Resource Bundle Type. This is the classic plain text file with keys and values where we'll store labels, descriptions and text in general.

Once you change the location of the bundle file, JDeveloper shows a warning message telling you that prior resource bundle will not be moved to the new location and instead you should do it yourself. But if you are configuring i18n for a new project, this is not an issue. Now, you just have to create the bundle file:

Right click on the ViewController project and select the New... option:

 From the opening dialog,  select General on the left and on the right select File:

Then, use the same name for the bundle file you configured in previous steps (ApplicationBundle) but as you are configuring a Properties Bundle file, you have to use the suffix .properties. Also, put the file in the correct folder, again, this should be the same folder you configured in the project properties:

Finally, the following configuration is needed in order to allow the bundle to be accessed by your managed beans. Open the faces-config.xml file located in your ViewController project under the Web Content/WEB_INF folder and select the Application tab.

On the right, in the Message Bundle field, insert the full path of your bundle file. You configured this path in previous steps. 

In the same screen, under Locale Config, you can establish your Default Locale and any other locales you need in your project (using the green cross button). Notice that you don't have to insert anything under Resource Bundle because we are going to use the ADF features for resource bundles.

The following image shows the previous configuration:

Updating the bundle file
Next we can find the bundle file we created previously with some messages added:

We can add or update any of the messages in the resource bundle file directly. Double click on the file and JDeveloper opens it in the right panel. If you are going to update this file directly, please note that you need to insert unicode text. There is another way to update this file and is by using one of the features that JDeveloper offers. Select the Application menu and then the Edit Resource Bundles... option:

Using this option we can modify or add new messages to the bundle file of the current application. Once selected, a dialog opens presenting you the messages found in the bundle file and buttons to create or delete messages. It is important to notice that using this option we can't modify the key part of the messages only their values:

Using the resource bundle file in web pages

Once our resource bundle file is configured, we can use it in our web pages/fragments. In order to do so, we need to open the properties of the component that we want to set its message (text, description, etc...). The following image shows the properties for a button component and the option we need to select in order to obtain a message for it:

Once we click on  Select Text Resource, we are asking JDeveloper to show us the different messages configured in the ResourceBundle of the project, so we can assign one message to the component property (text, description, etc...). On the same dialog, we have the chance to define a new message and use it:

Once we start using the features that JDeveloper offers when translating our texts, you may notice the insertion of the following code in your pages/fragments:

This way we can have all of our components texts in one file and then we only need to translate each file to the languages we want for the application.


Translating a resource bundle

When you finish your app and have decided the languages in which your application needs to display texts and messages, all you need to do is create another file, using the same location as the bundle file you have already created and name it with the same name plus underscore plus the language code. For instance, for spanish translation, if our bundle file is ApplicationBundle.properties then, the new file for spanish language should be called ApplicationBundle_es.properties, for french language you should use ApplicationBundle_fr.properties, and so on... Finally, just translate each file and ADF will do the rest.

By using this approach our application is ready to display texts and messages in the browser's language. In a future post, we will cover how we can let the user select the appropriate language. 

see ya!

References:

JDeveloper 11.1.2.3 - Internationalizing and Localizing Pages. Oracle [online].
Available on Internet: http://docs.oracle.com/cd/E35521_01/web.111230/e16181/af_global.htm
[accessed on February 11 2012].

Sten E. Vesterli (2011). Oracle ADF Enterprise Application Development Made Simple. United Kingdom: Packt Publishing Ltd.