[DISCUSSION] PROPOSAL for Commons Locale (or Jakarta Internationalization)

[Robert Simpson <RS...@Verizon.net>]

This is a preliminary proposal for a component that provides a consistent mechanism for handling "Internationalization" issues.  One point of discussion is whether this function should be provided as a component under the Commons subproject, or as a full-fledged "Internationalization" Jakarta subproject.

----------------------------------------------------------------------------------------------------
Proposal for Commons Locale component

This is a proposal for creating a Locale component in the Jakarta Commons
subproject, superseding and encompassing the "Resources" component
that is currently in the Jakarta Commons sandbox.

An HTML version of this proposal can be found at http://iToolSet.com/locale/PROPOSAL.html


0) Rationale

There are many different types of Java(TM)* objects that may be included in
Java applications that support internationalization (i18n).  These include
resources, message strings, formatters, Calendars, Currency objects, TimeZones,
Exceptions, Collators, and BreakIterators, among others.

There currently is a "Resources" component in the Jakarta Commons sandbox.
However, there should be a common architecture for internationalization of any
object, not one that is limited to Resources.  Therefore, a "Locale" component
should be added to the Jakarta Commons proper.  The functions provided by the
"Resources" component currently in the sandbox could be provided in a subpackage
under the package created for the new Locale component.


1) Scope of the Component

The proposal defines a common framework for internationalization of various
Java classes.  This internationalization typically occurs by localizing
instances of Java objects to a specific Locale.  The proposed framework would
facilitate the internationalization of all objects to a single Locale per user,
in either a single-user or multi-user environment.  For example, when localizing
messages, both the message patterns and the inserted arguments should be localized
to the same Locale.  This is a good example of why internationalization should occur
at a higher level than simply the resources that supply the localized message patterns.

Two interfaces, "Localizable" (used by classes that implement both a get and
set method for the Locale) and "Localized" (for classes that implement a get method
only) would be defined.  Other implementers would be encouraged to declare their
classes with one of these interfaces where appropriate.  Where this occurs, any
Factory classes which generate localized/localizable (localized/able) versions of
those objects would be included in that same package, rather than under the Locale
component.  This is appropriate, since it makes sense to keep the Factory and the
base class or interface it creates in the same package.  In contrast, for classes
provided by Sun Microsystems or third parties, where the source code could not be
modified, a localized/able subclass of the Sun/third party class would be created
within the Locale component, typically in a subpackage structure that in some way parallels
the structure in which the base class resides (in the initial code, this has already
been done for most of the Java SDK classes).  This would allow other Jakarta
subprojects and components to locate and include such classes in a consistent manner.

1.5) Interaction With Other Subpackages and Components

In the initial code, there are a number of classes that abstract various classes provided
in different versions of the Java SDKs that can be used for configuration parameters (Properties,
Preferences, and the Preferences SPI).  These classes might be most appropriately placed in the
Jakarta Commons Util component (with specific implementations in "props" and "prefs" subpackages).
If this was not acceptable, those classes could be placed under the Locale component.

The proposed component will probably contribute only to other components within the Jakarta
Commons subproject, primarily the "util" (as mentioned above) and possibly "lang" component.
On the other hand, it is expected that other components and subpackages will make use of the
Locale component anywhere they need to provide for internationalization of their objects,
resulting in much heavier interaction inbound rather than outbound, which should be typical
of the Commons subpackage in general.


2) Initial Source of the Package

The initial source of the package would be obtained from existing code (after the
addition of comments to meet Apache requirements), which can be found in a .zip file
that can be downloaded from http://iToolSet.com/locale/CommonsLocale.zip.  This code
has been revised somewhat to demonstrate how it might appear in the Apache world, and
to provide a working example.  The example, which simulates the use of localized resources
in a multi-user (ex: servlets) environment with both local client-side (multiple users with
distinct locales) and remote server-side (single server with it's own locale) destinations,
can be run by executing the "test2.bat" batch file or the "test2.sh" shell script.
(The test is currently set up to run under version 1.4).
The JavaDoc for the initial code can be found http://iToolSet.com/locale/docs/index.html".

Code for new classes, such as for Factory classes that could produce Localized instances of objects
for third-party classes could be submitted by other developers, most likely via communication
with one or more of the committers for this component or the Commons subproject.  The committer(s)
would verify conformance with the interfaces, scope and principles of this component before
permanently adding the new classes.


3) Required Jakarta-Commons Resources

CVS Repository

    New directory "locale" in the
    "jakarta-commons" CVS repository.  Revise initial
    committers based on initial committers list (below).

    Revise committers list or designate contact with committer privileges for
    subpackages for classes which may be more appropriately placed in other Jakarta
    Commons components (see "Interaction with Other Packages and Components" above).

    Create "props" and "prefs" subdirectories under the Commons "util" directory.
    Check in the initial code for abstraction of Sun's "java.util.Properties" and
    "java.util.prefs.Preferences" classes into those three directories.

Mailing List

    Discussions will take place on the general Jakarta
    "commons-user" and "commons-dev" mailing lists.  To help
    list subscribers identify, sort or filter messages of interest, it is suggested that
    the message subject of messages about this component be prefixed with "[Locale]".

Bugzilla

    New component "Locale" under the "Commons" product
    category, with appropriate version identifiers as needed.


4) Initial Committers

The initial committers on the Locale component shall be Robert Simpson and,
tentatively, Craig McClanahan, Michael Schachter, Jason van Zyl, and Daniel Rall.
(For the "tentative" committers, who had some interest in the Resources component,
an e-mail would be sent to them asking if they would still be willing to be committers
for the Locale component.  They would be included in the committers list based on
their agreement.)


* Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org

Re: [DISCUSSION] PROPOSAL for Commons Locale (or Jakarta Internationalization)

[Stephen Colebourne <sc...@btopenworld.com>]

From: "Robert Simpson" <RS...@Verizon.net>
> The proposal defines a common framework for internationalization of
various
> Java classes. This internationalization typically occurs by localizing
> instances of Java objects to a specific Locale.  The proposed framework
would
> facilitate the internationalization of all objects to a single Locale per
user,
> in either a single-user or multi-user environment.  For example, when
localizing
> messages, both the message patterns and the inserted arguments should be
localized
> to the same Locale.  This is a good example of why internationalization
should occur
> at a higher level than simply the resources that supply the localized
message patterns.
>
> Two interfaces, "Localizable" (used by classes that implement both a get
and
> set method for the Locale) and "Localized" (for classes that implement a
get method
> only) would be defined.  Other implementers would be encouraged to declare
their
> classes with one of these interfaces where appropriate.  Where this
occurs, any
> Factory classes which generate localized/localizable (localized/able)
versions of
> those objects would be included in that same package, rather than under
the Locale
> component.  This is appropriate, since it makes sense to keep the Factory
and the
> base class or interface it creates in the same package.  In contrast, for
classes
> provided by Sun Microsystems or third parties, where the source code could
not be
> modified, a localized/able subclass of the Sun/third party class would be
created
> within the Locale component, typically in a subpackage structure that in
some way parallels
> the structure in which the base class resides (in the initial code, this
has already
> been done for most of the Java SDK classes).  This would allow other
Jakarta
> subprojects and components to locate and include such classes in a
consistent manner.

I have difficulty with an API that mandates one locale for the user. In my
day job, the system uses two locales - a display locale and a system locale.
The display locale is the language that the web page should be returned in,
the system locale handles things like what currency should be used (eg.
Canada - two languages, one currency).

I kinda feel there are various possible solutions to handling locale issues,
each of which may be valid depending on your situation:
- context - the application might pass a context object to each method, from
which one or more locales can be extracted.
- aspects - AspectJ solutions could probably factor out locale behaviour
- subclass - this is the route you've adopted

Your code demonstrates that it requires a lot for subclassing to work. A lot
of new classes, new things to learn, etc - as with any framework.
Essentially, you are trying to make classes in the JDK implement new
interfaces, something that always seems to end in tears.

It occurs to me that the majority of what you are trying to achieve with the
subclasses could be achieved using reflection:
  void  LocaleUtils.setLocale(Object object, Locale loc)
  Locale  LocaleUtils.getLocale(Object object);
This seems a less intrusive solution...

On a side note, you may find that the Avalon project at Apache may be
interested in the framework. They are the server side framework group
(framework perhaps being significant here). (They are undergoing major
changes at present though)

> In the initial code, there are a number of classes that abstract various
classes provided
> in different versions of the Java SDKs that can be used for configuration
parameters (Properties,
> Preferences, and the Preferences SPI).  These classes might be most
appropriately placed in the
> Jakarta Commons Util component (with specific implementations in "props"
and "prefs" subpackages).
> If this was not acceptable, those classes could be placed under the Locale
component.

FYI, the Util component no longer exists in commons. Code is now in IO,
Collections and Lang.

Stephen


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org