com.lf.commons.i18n

Class I18NConfiguration

java.lang.Object

com.lf.commons.config.Configuration

com.lf.commons.i18n.I18NConfiguration

public class I18NConfiguration
extends Configuration

Provides specialized functionality to manage localized texts automatically.

Localized texts are shipped in the form of configuration files *.conf. Each class cares for it own localization to keep the packages widely usable. To help the developer while localizing the classes this subclass provides both ways, localizing a given object by evaluating the defined patterns like special global fields or GUI components with setText() and setToolTipText() methods and also getting the values from the instances. This can be useful to automatically detect new localized fields which have to be translated in the available localizations.

Use the configuration as usual (sets variables, read and write) and the additional methods localize() and extractLocalization(). The object specified for the localize() method is then analyzed for localization patterns, in the second step the global variables are loaded with the localized values from the configuration. In turn the extractLocalization() reads the localized texts from the given object and stores them into the configuration to be stored or otherwise processed.

The localization patterns are specially declared fields. All fields no matter the modifiers (public, protected etc.) will be used. The field candidates must have either a name prefix "I18N_" or a name suffix "_I18N" (in other words must start or end with "I18N" separated by underscore '_' from the rest of the name):

     // An example for straight localization
     public String I18N_UPDATES_AVAILABLE = "Updates are available!";

     // An example for GUI component localization
     protected JMenuItem menuItemCheckFile_I18N = new JMenuItem();
     ...
     this.menuItemCheckFile_I18N.setText("Check Files...");
     this.menuItemCheckFile_I18N.setToolTipText("Choose a file to be checked");
     ...
 

Normally GUI can be easily localized using this class. The declared components applying to the above described localization pattern are collected and then localized. For text components like JLabel the setText() and setToolTipText() methods are used. Other components may have additional localized fields, see the documentation for supported properties. Besides GUI components localization must support direct string setting since most classes assemble texts from fragments or create components locally. These fields must also be declared as described above and may only be of the type String. For example the above mentioned fields would be stored using the class names in FQN as follows:

     com.lf.digester.gui.Digester.UPDATES_AVAILABLE=Updates are available!

     com.lf.digester.gui.DigesterView.menuItemCheckFile.text=Check Files...
     com.lf.digester.gui.DigesterView.menuItemCheckFile.tooltip=Choose a file to be checked
 

Another way of defining localized fields is using the annotation type Localize. In classes with many localized fields the overhead added by the fields and their reflection based runtime localization would be very inefficient so annotations come into play. They allow for extraction of desired localization fields (variables) and the default values (English) while keeping the classes small. Localization annotations can easily be added to the default constructor which must exist for value extraction since instance fields are accessed. The following example declares two localization fields:

     // Add to default constructor
     @Localize({
     @Localize.Variable(name = "TITLE", value = "Arguments"),
     @Localize.Variable(name = "NONE", value = "(none)")})
     public ArgumentTab () {
     ....

     com.lf.commons.dialog.status:ArgumentTab.TITLE=Arguments
     com.lf.commons.dialog.status:ArgumentTab.NONE=(none)
 

Remember that only non-final string fields can be loaded with localized values. The fields are separated with the ':' character to enable obfuscation (dots did not work, although they would be more natural in this scenario).

Since:

1.6

Version:

$Revision: 1.11 $, $Date: 2012/12/28 18:09:36 $

Author:

Axel Schwolow

Field Summary

Fields

Modifier and Type	Field and Description
static int	PREFIX_CLASS Indicates that class prefixes in FQN shall be prepended.
static int	PREFIX_NONE Indicates that the variables have no prefix.

Fields inherited from class com.lf.commons.config.Configuration

clearBeforeRead, comment, compression, COMPRESSION_DEFLATED, COMPRESSION_GZIPPED, COMPRESSION_UNCOMPRESSED, encoding, ENCODING_ISO_8859_1_UNICODE_ESCAPES, handlers, hash, sorting

Constructor Summary

Constructors

Constructor and Description
I18NConfiguration() Constructor method.

Method Summary

Methods

Modifier and Type	Method and Description
int	extractLocalization(java.lang.Class clazz, int prefix) Searches for localization annotations and reads the object texts into the configuration.
int	extractLocalization(java.lang.Object target, int prefix) Searches for localization patterns and reads the object texts into the configuration.
int	localize(java.lang.Object target, java.lang.Class targetclazz, int prefix) Searches for localization patterns and sets the object texts from the configuration.
static java.lang.String	normalizeField(java.lang.String fieldname, java.awt.Component comp) Returns a normalized version of the given field name.

Methods inherited from class com.lf.commons.config.Configuration

clear, contains, equals, finalize, getBoolean, getBoolean, getByte, getByte, getCache, getChar, getChar, getClearBeforeRead, getComment, getCompression, getDouble, getDouble, getEncoding, getFloat, getFloat, getHandler, getHandler, getHandlers, getInt, getInt, getLong, getLong, getObject, getObject, getObject, getObject, getShort, getShort, getSupportedClassTypes, getSupportedTypes, getVariable, getVariables, isEmpty, isOrdered, isSecure, isSorting, isTypeSupported, isTypeSupported, read, read, read, read, readConvertProperties, readXML, readXML, readXML, readXML, remove, removeAllHandlers, removeHandler, removeHandler, removeStartsWith, setBoolean, setByte, setChar, setClearBeforeRead, setComment, setCompression, setDouble, setEncoding, setFloat, setHandler, setInt, setLong, setObject, setOrdered, setSecure, setSecure, setShort, setSorting, setVariable, size, write, write, write, write, writeXML, writeXML, writeXML, writeXML

Methods inherited from class java.lang.Object

clone, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PREFIX_CLASS

public static final int PREFIX_CLASS

Indicates that class prefixes in FQN shall be prepended.

See Also:

Constant Field Values

PREFIX_NONE

public static final int PREFIX_NONE

Indicates that the variables have no prefix.

See Also:

Constant Field Values

Constructor Detail

I18NConfiguration

public I18NConfiguration()

Constructor method.

Since:

1.6

Method Detail

localize

public int localize(java.lang.Object target,
           java.lang.Class targetclazz,
           int prefix)

Searches for localization patterns and sets the object texts from the configuration.

Remember that this method only processes the fields declared by the targetclazz which may be the class type of the given object or one of its superclasses. This allows applications for full control of automatic localization, but it is necessary to call the localize() method from every subclass that has localization patterns.

Parameters:

target - The target object to be localized

targetclazz - The target clazz, maybe a superclass

prefix - The mode of prefixing (PREFIX_CLASS|...)

Returns:

Number of successfully synchronized fields

Throws:

java.lang.NullPointerException - If parameters are invalid

java.lang.IllegalArgumentException - If parameters are invalid

Since:

1.6

extractLocalization

public int extractLocalization(java.lang.Object target,
                      int prefix)

Searches for localization patterns and reads the object texts into the configuration.

Annotations can be analzed separately by calling the other extractLocalization() method which works simply on class references instead of instances in order to enable abstract classes to be analyzed.

Parameters:

target - The target object to be analyzed

prefix - The mode of prefixing (PREFIX_CLASS|...)

Returns:

Number of successfully retrieved fields

Throws:

java.lang.NullPointerException - If parameters are invalid

java.lang.IllegalArgumentException - If parameters are invalid

Since:

1.6

extractLocalization

public int extractLocalization(java.lang.Class clazz,
                      int prefix)

Searches for localization annotations and reads the object texts into the configuration.

This method is separate since we only need the class reference and no instance to analyze the constructor annotations. Abstract classes cannot be instantiated but also provide localization functionality, the other method could not be used for pattern extraction.

Parameters:

clazz - The target clazz to be analyzed

prefix - The mode of prefixing (PREFIX_CLASS|...)

Returns:

Number of successfully retrieved fields

Throws:

java.lang.NullPointerException - If parameters are invalid

java.lang.IllegalArgumentException - If parameters are invalid

Since:

1.6

normalizeField

public static java.lang.String normalizeField(java.lang.String fieldname,
                              java.awt.Component comp)

Returns a normalized version of the given field name.

If the name is omitted then the getName() method is called for the given component.

Parameters:

fieldname - The field name to be normalized (optional)

comp - The component (optional)

Returns:

Normalized field name

Throws:

java.lang.NullPointerException - If parameters are null

java.lang.IllegalArgumentException - If both parameters are missing

Since:

1.6