Using MyFaces with Oracle JDeveloper 10g (10.1.3) Preview
Localizing JSF and ADF Faces applications
Written by Jonas Jacobi, Oracle Corporation
August, 2005
Revision 1.0
An article about localizing a JSF and ADF Faces application
This article explains how to internationalize an ADF Faces and JSF
application. The article will also make some comparisons with JSF core
components and ADF Faces equivalent components regards to what level of support
for locales are provided. Oracle JDeveloper 10g (10.1.3) Preview
will be used to illustrate and build the actual application. This article
is divided into two parts - one that is explaining the core setup to enable
locale support with JSF core components, and the second part is covering the
same scenario using
Oracle ADF Faces components and comparing the two component sets. For more information and
articles, please, refer to the
JDeveloper
page,
ADF Faces page, and
JSF Resource page on Oracle
Technology Network (OTN).
As many of you are already aware locale means not just a language it can also
mean language AND region. In some cases it may by just enough to specify a
language e.g. Finish is only spoken in Finland whereas Swedish spoken in Sweden
is different than Swedish spoken in Finland. Same scenario applies to US English
and British English. There is a difference in the term localize and
internationalize. The first term - localize - means that you have prepared your
application by extracting labels and text to a resource bundle, which allow
labels and text to be determined by the locale. This resource bundle can then be
shipped off for translation and used to internationalize your application.
Let's start with building a simple page using components provided by the Sun
RI:
Create a new Application by selecting File -> New -> General ->
Application. Click OK.
In the Create Application dialog enter 'Localize' as application
name. Keep the rest as default and click OK.
In the Create Project dialog enter 'view' as project name.
To add a new JSF JSP page to the project right click on the view project
and select New ...
Expand the Web Tier node and select JSF category.
In the right pane select JSF JSP and click OK.
In the Create New Page wizard set the file name to jsf_core and the page
type to JSP Document. Note: The page type is optional.
Click Finish.
You have now created the page that we are going to use for the JSF core
localization. Before we start to localize the page we need to add some controls
that can be used for this exercise.
Open the jsf_core.jspx page in the visual editor by double
clicking on the node in the project.
In the Component Palette switch to the JSF HTML category.
Drag and drop an outputText component from JSF HTML category onto
the page. This is going to be our title.
Set the Value property to Welcome. This will be changed later to use the
resource bundle that we are going to create.
Hit Enter key after the outputText field to create a new row in the
page.
Drag and drop an outputText component onto the page, and set the
Value property to 'label'.
Note: The For property is used to "wire" the outputLabel component to the
"parent" component using the label.
Drag and drop an inputText component onto the page just after the
outputText component that is our label.
Drag and drop a commandButton onto the page and drop it after the
inputText field.
Set the Value property on the button to 'Press here!'.
For additional chrome on the page set apply a H2 style to the outputText
component at the top of the page since it is our title.
In the Component Palette change category to CSS and drag and drop a the
JDeveloper stylesheet onto the page.
Your page should look like this:
Now it is time to isolate our labels and text messages and extract them and
insert them into a resource bundle. A resource bundle can either be a Java file
or a .properties file. In this sample we are going to use the .properties
approach. As y ou have noted this sample does not contain that many strings
to extract, but the format for which we enter our translatable strings is key.
The format for which you enter in the property file is key, an equal
sign, and the text string representing the label or message. Here is
an example:
Key
Equal sign
Message
myLabel
=
Welcome Mr/Mrs,
myButton
=
Press here!
You place the key/value pair in a plain text file with the file extension
.properties. It is important that you follow a certain pattern when you name
your properties file. If the file will contain your default language you only
need to give the .properties file a name e.g. myBundle.properties, but if it is
depending on a specific locale you will have to append the _LOCALE to file
following the rule <name_of_base_file>_LOCALE.properties e.g.
myBundle_de.properties for German, myBundle_sv.properties for
Swedish.
Let's create a simple property file in JDeveloper.
Right click on the view project node in the Application Navigator
and select New...
Select category General and in the right pane select File
and click OK.
Set the name and file extension of the file to - myBundle.properties.
Click on Browse to change the directory where we are going to store our
resource bundle.
In the Choose Directory dialog select the 'src' folder under the
view directory. This is to ensure that the resource bundle is in your class
path.
Press the Create New Subdirectory button at the top right and set
the name of the new directory to "myLocale".
Click OK to close the Create New Directory dialog.
When done creating the 'myLocale' directory make sure that the 'myLocale'
directory is selected and press Select to close the Choose Directory dialog.
Click OK to close the Create File dialog.
The file should now show up in JDeveloper, so that you can start editing it.
There is only one minor thing we need to do (if you don't see the file and the
parent folder in the Application Navigator) and that is to add our base folder for our bundles to the Application
Navigator.
Double click on the view project node to open the Project Properties
dialog.
In the Project Properties dialog expand the Project Content node
and select Resources.
Make sure that the 'Include
Subfolders' option is checked for the added directory before clicking OK
to close the Project Properties.
You should now see your directory structure in the Application
Navigator.
If not open in the editor, double click on the myBundle.properties file
to open.
In the file add the key/value pairs:
myTitle = Welcome Mr/Mrs,
myLabel = Enter your name:
myButtonText = Press here!
Save the file.
Now when we have one properties file containing one locale we can start
making our page utilizing this. In JSF there is component called
<f:loadBundle> that lets you load a
resource bundle into your page and access the keys in this bundle using VBL e.g.
#{myBundle.myBundle.myTitle}. The
<f:loadBundle> contains a
var property that can be used to
define a variable or access point to the properties file. You can then use this
variable to access your keys and if for some reason the resource bundle changes
you only have to change it in one place <f:loadBundle
basename="myBundle.myBundle" var="sampleBundle">. Here is an example of
how it could be used:
It is important that you add the <f:loadBundle>
just below the <f:view> component at
the top of your page, otherwise components referring to this bundle will not be
able to "see" the var handle.
Let's use the myBundle.properties file in our page.
Open the jsf_core.jspx file in the visual editor
From the Component Palette drag and drop the
<f:loadBundle> located in the
JSF Core category onto the page.
In the Insert LoadBundle dialog enter 'myLocale.myBundle' for the
basename property and 'sampleBundle' for the var property.
Make sure it is at top of the page just underneath the
<f:view> component. Note: If it is hard to get it in the right place you use the Structure
Window to move it.
Before:
After:
Select the outputText component that represent our title and set
the Value property to the following:
#{sampleBundle.myTitle}
Select the outputText component that represent our label
and set the Value property to the following:
#{sampleBundle.myLabel}
Select the commandButton component and set the Value property to
the following:
#{sampleBundle.myButtonText}
Save your page. You should now see the resource string applied to the
page's components.
Locate the faces-config.xml file and double click to open in the editor.
The file is located under the WEB-INF directory
In the faces-config.xml editor select the Overview tab.
In the list to the left select Application. You should now see the
following:
In the 'Locale Config' section set the default locale to - en
Click on the New button to add a new locale. In the dialog enter
- sv
Save your work.
You can now run your application and the application will pick up the locale
from the browser settings. If you want to change the local and see the effect
immediately in the browser after a refresh you will have to perform the
following configuration steps.
Locate the web application deployment descriptor - WEB.XML.
Right click on the WEB.XML file and select Properties from the
popup menu.
Click on the Context Initialization node and click on the Add button.
In the dialog that appear add the following:
Name = "javax.faces.STATE_SAVING_METHOD"
Value = "client"
You have now done all your localization and internationalized your
application to support both English and Swedish. You now want to use ADF Faces
components in your application.
Right click on the View project and select New...
Expand the Web Tier node and select JSF category.
In the right pane select JSF JSP and click OK.
In the Create New Page wizard set the file name to adf_faces and the page
type to JSP Document.
Select Next.
In this step add the two ADF Faces libraries to your page - ADF Faces
components EAxx and ADF Faces HTML EAxx
From the Component Palette under the ADF Faces Layout category drag and
drop a PanelPage component onto the page.
Set the Title property on this component to - #{sampleBundle.myTitle}
From the Component Palette under the ADF Faces Input category drag and
drop a inputText component onto the page. As you can see this component is
similar to the core JSF inputText component except that you don't need to
attach a label to it, basically it is simpler to use.
Set the Label property on this component to - #{sampleBundle.myLabel}
From the Component Palette under the ADF Faces Navigation category drag and
drop a commandButton component onto the page.
Set the Text property on this component to - #{sampleBundle.myButtonText}
Save your work and run your page.
In order to show the full benefit of using ADF Faces components compared to
the components provided by the RI you need to add iw to the 'Locale
Config' in the faces-config.xml file and when you run the page change your browser language
settings to Hebrew.
This will show off the built-in support for different locales in ADF Faces (in
this case without translated strings to Hebrew). As you will see ADF Faces
provides the ability to read and write from right to left, which is not
which is not provided by the core components.
Bookmark
