Internationalization: which bundle type is right for you?

Choice is one of the fundamental tenets of JDeveloper's approach to development. This probably explains why so many people on the OTN forums and the ADF Enterprise Methodology Group ask for guidance on picking the best alternative to handle specific use cases. Most of the time, the answer will start with: Well... It depends. Developer skills, functional requirements, performance expectations and other variables make it difficult to come up with a single, straightforward recommendation. This is the case with resource bundles. 

In the context of the Java platform, a resource bundle is simply a collection of objects related to a specific locale. Each object can be retrieved by its key, which must be unique among all the bundles available to an application. When a program needs a locale-specific resource, such as the string for an error message, it can load it from the resource bundle that is appropriate for the current user's locale. This mechanism allows you to write programs that can:

  • be easily localized, or translated, into different languages
  • handle multiple locales at once
  • be easily modified later to support even more locales
    Source: Javadoc for the ResourceBundle class. 

JDeveloper supports three different types of resource bundles: Java classes, .properties files and XLIFF files. All three behave exactly in the same way at runtime; choosing one type or the other will be completely transparent to the end user and will not likely impact performance or resource usage in a well-designed application. Why would you pick one type over the other, then?

.properties files represent the simplest, most straightforward alternative. Here is a sample file. - Jan 20, 2013 
PASSWORD_EXPIRED=You password has expired. Please change it.
DATABASE=Database updated. The application will now restart. 

They are very easy to update even by non-programmers, since their format is so simple. And the ADF  Faces Skin Editor will use them if you override default ADF text resources in your skin. JDeveloper always makes sure to encode such bundles properly at deployment time; that way, international characters are always rendered properly. 

You can also use Java classes as resource bundles. In JDeveloper, they are called List Bundles. They are your only option if you want to manage non-string objects or if you need to implement bundle-related business logic. A Java class bundle, for example, could be used to retrieve text strings stored in the database. A typical Java class bundle is reproduced below.

public class MyResources extends ListResourceBundle {

protected Object[][] getContents() { return new Object[][] { {"PASSWORD_EXPIRED", "You password has expired. Please change it."}, {"DATABASE", "Database updated. The application will now restart."}, }; } }

Typically, Java class bundles add complexity to the translation workflow, since classes with updated resources must be recompiled and redeployed. Moreover, non-technical users risk to introduce errors in the code when adding new strings or updating existing ones. It is worth noting that the ADF framework itself stores most of its massages and boilerplate text in Java class resource bundles. 

XLIFF (XML Localisation Interchange File Format) is a standard managed by the OASIS consortium. It is supported by specialized tools used by translators, which constitutes its main draw over alternatives. Because of its open nature, XLIFF lends itself a much wider set of use cases than just resource management.  The following XLIFF bundle has been built using JDeveloper 11gR2.

<?xml version="1.0" encoding="UTF-8" ?> <xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1"> <file source-language="en" original="view.ViewControllerBundle" datatype="x-oracle-adf"> <body> <trans-unit id="PASSWORD_EXPIRED"> <source>You password has expired. Please change it.</source> <target/> <note>Message displayed on the logging page when the user password has expired.</note> </trans-unit> <trans-unit id="DATABASE"> <source>Database updated. The application will now restart.</source> <target/> <note>Admin message for use by the batch subsystem. Found in logs.</note> </trans-unit> </body> </file> </xliff>

As you can see, XLIFF is much more verbose than either Java classes or property files. 

So, which bundle type is right for you? Well... It depends. ;-) Usually, .properties file will be enough and you will bother with XLIFF's verbosity only if your translators use tools that support it. Java class bundles, on the other hand, are the only way to implement some use cases involving custom business logic but do not necessarily make sense outside specific contexts.


Thanks, this one is a very nice explanation about various options of localizing content using ADF technology.

Posted by guest on March 24, 2014 at 10:45 PM EDT #


Is it possible to use placeholders in a message, like "Welcome {0}"?
The placeholder "{0}" must be replaced by the name of the user.


Posted by Robbert on September 13, 2014 at 07:06 AM EDT #


Sure! This blog post explains you how:

Best Regards,


Posted by BlueberryCoder on September 15, 2014 at 09:05 AM EDT #

Post a Comment:
  • HTML Syntax: NOT allowed

Frédéric Desbiens

The musings of a member of the Mobility and Development Tools Product Management team.

I focus here on my favorite development frameworks, namely Oracle ADF and the Oracle Mobile Application Framework (MAF), but also have a strong interest in SOA and web services.

The views expressed on this blog are my own and do not necessarily reflect the views of Oracle.


« July 2016