This class provides support for multi-language string lookup, as needed
to localize messages from applications supporting multiple languages
at the same time. One class of such applications is network services,
such as HTTP servers, which talk to clients who may not be from the
same locale as the server. This class supports a form of negotiation
for the language used in presenting a message from some package, where
both user (client) preferences and application (server) support are
accounted for when choosing locales and formatting messages.
Each package should have a singleton package-private message catalog
class. This ensures that the correct class loader will always be used to
access message resources, and minimizes use of memory:
package some.package;
// "foo" might be public
class foo {
...
// package private
static final Catalog messages = new Catalog ();
static final class Catalog extends MessageCatalog {
Catalog () { super (Catalog.class); }
}
...
}
Messages for a known client could be generated using code
something like this:
String clientLanguages [];
Locale clientLocale;
String clientMessage;
// client languages will probably be provided by client,
// e.g. by an HTTP/1.1 "Accept-Language" header.
clientLanguages = new String [] { "en-ca", "fr-ca", "ja", "zh" };
clientLocale = foo.messages.chooseLocale (clientLanguages);
clientMessage = foo.messages.getMessage (clientLocale,
"fileCount",
new Object [] { new Integer (numberOfFiles) }
);
At this time, this class does not include functionality permitting
messages to be passed around and localized after-the-fact. The consequence
of this is that the locale for messages must be passed down through layers
which have no normal reason to support such passdown, or else the system
default locale must be used instead of the one the client needs.
The following guidelines should be used when constructiong
multi-language applications:
- Always use chooseLocale to select the
locale you pass to your
getMessage
call. This lets your
applications use IETF standard locale names, and avoids needless
use of system defaults.
- The localized messages for a given package should always go in
a separate resources sub-package. There are security
implications; see below.
- Make sure that a language name is included in each bundle name,
so that the developer's locale will not be inadvertently used. That
is, don't create defaults like resources/Messages.properties
or resources/Messages.class, since ResourceBundle will choose
such defaults rather than giving software a chance to choose a more
appropriate language for its messages. Your message bundles should
have names like Messages_en.properties (for the "en", or
English, language) or Messages_ja.class ("ja" indicates the
Japanese language).
- Only use property files for messages in languages which can
be limited to the ISO Latin/1 (8859-1) characters supported by the
property file format. (This is mostly Western European languages.)
Otherwise, subclass ResourceBundle to provide your messages; it is
simplest to subclass
java.util.ListResourceBundle
.
- Never use another package's message catalog or resource bundles.
It should not be possible for a change internal to one package (such
as eliminating or improving messages) to break another package.
The "resources" sub-package can be treated separately from the
package with which it is associated. That main package may be sealed
and possibly signed, preventing other software from adding classes to
the package which would be able to access methods and data which are
not designed to be publicly accessible. On the other hand, resources
such as localized messages are often provided after initial product
shipment, without a full release cycle for the product. Such files
(text and class files) need to be added to some package. Since they
should not be added to the main package, the "resources" subpackage is
used without risking the security or integrity of that main package
as distributed in its JAR file.
chooseLocale
public Locale chooseLocale(languages[] )
Chooses a client locale to use, using the first language specified in
the list that is supported by this catalog. If none of the specified
languages is supported, a null value is returned. Such a list of
languages might be provided in an HTTP/1.1 "Accept-Language" header
field, or through some other content negotiation mechanism.
The language specifiers recognized are RFC 1766 style ("fr" for
all French, "fr-ca" for Canadian French), although only the strict
ISO subset (two letter language and country specifiers) is currently
supported. Java-style locale strings ("fr_CA") are also supported.
- The most preferable supported locale, or null.
getMessage
public String getMessage(Locale locale,
String messageId)
Get a message localized to the specified locale, using the message ID
and package name if no message is available. The locale is normally
that of the client of a service, chosen with knowledge that both the
client and this server support that locale. There are two error
cases: first, when the specified locale is unsupported or null, the
default locale is used if possible; second, when no bundle supports
that locale, the message ID and package name are used.
locale
- The locale of the message to use. If this is null,
the default locale will be used.messageId
- The ID of the message to use.
- The message, localized as described above.
getMessage
public String getMessage(Locale locale,
String messageId,
parameters[] )
Format a message localized to the specified locale, using the message
ID with its package name if none is available. The locale is normally
the client of a service, chosen with knowledge that both the client
server support that locale. There are two error cases: first, if the
specified locale is unsupported or null, the default locale is used if
possible; second, when no bundle supports that locale, the message ID
and package name are used.
locale
- The locale of the message to use. If this is null,
the default locale will be used.messageId
- The ID of the message format to use.
- The message, localized as described above.
isLocaleSupported
public boolean isLocaleSupported(String localeName)
Returns true iff the specified locale has explicit language support.
For example, the traditional Chinese locale "zh_TW" has such support
if there are message bundles suffixed with either "zh_TW" or "zh".
This method is used to bypass part of the search path mechanism
of the
ResourceBundle
class, specifically the parts which
force use of default locales and bundles. Such bypassing is required
in order to enable use of a client's preferred languages. Following
the above example, if a client prefers "zh_TW" but can also accept
"ja", this method would be used to detect that there are no "zh_TW"
resource bundles and hence that "ja" messages should be used. This
bypasses the ResourceBundle mechanism which will return messages in
some other locale (picking some hard-to-anticipate default) instead
of reporting an error and letting the client choose another locale.
localeName
- A standard Java locale name, using two character
language codes optionally suffixed by country codes.
- True iff the language of that locale is supported.