org.gvsig.i18n
Class Messages

java.lang.Object
  extended byorg.gvsig.i18n.Messages

public class Messages
extends java.lang.Object

This class offers some methods to provide internationalization services to other projects. All the methods are static.

The most useful method is getText(key) (and family), which returns the translation associated with the provided key. The class must be initialized before getText can be used.

The typical usage sequence would be:

The resource files are Java properties files, which contain key=translation pairs, one pair per line. These files must be encoded using iso-8859-1 encoding, and unicode escaped sequences must be used to include characters outside the former encoding. There are several ways to specify the property file to load, see the different addResourceFamily methods for details.

Author:
Cesar Martinez Izquierdo (cesar.martinez@iver.es)

Constructor Summary
Messages()
           
 
Method Summary
static void addLocale(java.util.Locale lang)
          Adds a Locale at the end of the ordered list of preferred locales.
static void addResourceFamily(java.lang.String family, java.lang.ClassLoader loader)
          Adds an additional family of resource files containing some translations.
static void addResourceFamily(java.lang.String family, java.lang.ClassLoader loader, java.lang.String callerName)
          Adds an additional family of resource files containing some translations.
static void addResourceFamily(java.lang.String family, java.io.File dir)
          Adds an additional family of resource files containing some translations.
static void addResourceFamily(java.lang.String family, java.io.File[] dirList)
          Adds an additional family of resource files containing some translations.
static void addResourceFamily(java.lang.String family, java.lang.String callerName)
          Adds an additional family of resource files containing some translations.
static java.lang.String getBaseLanguage()
          Gets the base language, the language considered the origin of translations, which will be (possibly) stored in a property file without language suffix (ie: text.properties instead of text_es.properties).
static java.util.ArrayList getPreferredLocales()
          Returns an ArrayList containing the ordered list of prefered Locales Each element of the ArrayList is a Locale object.
static java.io.File getResourceFile(java.lang.String dir, java.lang.String file_name)
           
static java.lang.String getString(java.lang.String key)
          Gets the localized message associated with the provided key.
static java.lang.String getText(java.lang.String key)
          Gets the localized message associated with the provided key.
static java.lang.String getText(java.lang.String key, java.lang.String callerName)
          Gets the localized message associated with the provided key.
static java.lang.String getText(java.lang.String key, java.lang.String[] arguments)
           
static java.lang.String getText(java.lang.String key, java.lang.String[] arguments, boolean log)
           
static java.lang.String getText(java.lang.String key, java.lang.String[] arguments, java.lang.String callerName)
           
static java.lang.String getText(java.lang.String key, java.lang.String[] arguments, java.lang.String callerName, boolean log)
           
static java.lang.String getText(java.lang.String key, java.lang.String callerName, boolean log)
          Gets the localized message associated with the provided key.
static boolean hasLocales()
          Checks if some locale has been added to the preferred locales list, which is necessary before loading any translation because only the translations for the preferred locales are loaded.
static boolean removeLocale(java.util.Locale lang)
          Removes the specified Locale from the list of preferred locales and the translations associated with this locale.
static void removeResources()
          Cleans the translation tables (removes all the translations from memory).
static void setBaseLanguage(java.lang.String lang)
          Sets the base language, the language considered the origin of translations, which will be (possibly) stored in a property file without language suffix (ie: text.properties instead of text_es.properties).
static void setPreferredLocales(java.util.ArrayList preferredLocalesList)
          Sets the ordered list of preferred locales.
static void setResourceDir(java.lang.String dir)
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Messages

public Messages()
Method Detail

setResourceDir

public static void setResourceDir(java.lang.String dir)

getText

public static java.lang.String getText(java.lang.String key,
                                       java.lang.String callerName)

Gets the localized message associated with the provided key. If the key is not in the dictionary, return the key and register the failure in the log.

The callerName parameter is only used as a label when logging, so any String can be used. However, a meaningful String should be used, such as the name of the class requiring the translation services, in order to identify the source of the failure in the log.

Parameters:
key - An String which identifies the translation that we want to get.
callerName - A symbolic name given to the caller of this method, to show it in the log if the key was not found
Returns:
an String with the message associated with the provided key. If the key is not in the dictionary, return the key. If the key is null, return null.

getText

public static java.lang.String getText(java.lang.String key,
                                       java.lang.String[] arguments,
                                       java.lang.String callerName)

getText

public static java.lang.String getText(java.lang.String key)

Gets the localized message associated with the provided key. If the key is not in the dictionary or the translation is empty, return the key and register the failure in the log.

Parameters:
key - An String which identifies the translation that we want to get.
Returns:
an String with the message associated with the provided key. If the key is not in the dictionary or the translation is empty, return the key. If the key is null, return null.

getText

public static java.lang.String getText(java.lang.String key,
                                       java.lang.String[] arguments)

getString

public static java.lang.String getString(java.lang.String key)

Gets the localized message associated with the provided key. If the key is not in the dictionary or the translation is empty, it returns null and the failure is only registered in the log if the param log is true.

Parameters:
key - An String which identifies the translation that we want to get.
Returns:
an String with the message associated with the provided key, or null if the key is not in the dictionary or the translation is empty.

getText

public static java.lang.String getText(java.lang.String key,
                                       java.lang.String[] arguments,
                                       boolean log)

getText

public static java.lang.String getText(java.lang.String key,
                                       java.lang.String callerName,
                                       boolean log)

Gets the localized message associated with the provided key. If the key is not in the dictionary, it returns null and the failure is only registered in the log if the param log is true.

Parameters:
key - An String which identifies the translation that we want to get.
callerName - A symbolic name given to the caller of this method, to show it in the log if the key was not found
log - Determines whether log a key failure or not
Returns:
an String with the message associated with the provided key, or null if the key is not in the dictionary.

getText

public static java.lang.String getText(java.lang.String key,
                                       java.lang.String[] arguments,
                                       java.lang.String callerName,
                                       boolean log)

addResourceFamily

public static void addResourceFamily(java.lang.String family,
                                     java.lang.ClassLoader loader)

Adds an additional family of resource files containing some translations. A family is a group of files with a common baseName. The file must be an iso-8859-1 encoded file, which can contain any unicode character using unicode escaped sequences, and following the syntax: key1=value1 key2=value2 where 'key1' is the key used to identify the string and must not contain the '=' symbol, and 'value1' is the associated translation.

cancel=Cancelar accept=Aceptar

Only one pair key-value is allowed per line.

The actual name of the resource file to load is determined using the rules explained in the class java.util.ResourceBundle. Summarizing, for each language in the specified preferred locales list it will try to load a file with the following structure: family_locale.properties

For example, if the preferred locales list contains {"fr", "es", "en"}, and the family name is "text", it will try to load the files "text_fr.properties", "text_es.properties" and finally "text_en.properties".

Locales might be more specific, such us "es_AR" (meaning Spanish from Argentina) or "es_AR_linux" (meaning Linux system preferring Spanish from Argentina). In the later case, it will try to load "text_es_AR_linux.properties", then "text_es_AR.properties" if the former fails, and finally "text_es.properties".

The directory used to locate the resource file is determining by using the getResource method from the provided ClassLoader.

Parameters:
family - The family name (or base name) which is used to search actual properties files.
loader - A ClassLoader which is able to find a property file matching the specified family name and the preferred locales
See Also:
ResourceBundle

addResourceFamily

public static void addResourceFamily(java.lang.String family,
                                     java.io.File[] dirList)
                              throws java.net.MalformedURLException

Adds an additional family of resource files containing some translations. The search path to locate the files is provided by the dirList parameter.

See addResourceFamily(String, ClassLoader) for a discussion about the format of the property files and the way to determine the candidat files to load. Note that those methods are different in the way to locate the candidat files. This method searches in the provided paths (dirList parameter), while the referred method searches using the getResource method of the provided ClassLoader.

Parameters:
family - The family name (or base name) which is used to search actual properties files.
dirList - A list of search paths to locate the property files
Throws:
java.net.MalformedURLException
See Also:
ResourceBundle

addResourceFamily

public static void addResourceFamily(java.lang.String family,
                                     java.io.File dir)
                              throws java.net.MalformedURLException

Adds an additional family of resource files containing some translations. The search path to locate the files is provided by the dir parameter.

See addResourceFamily(String, ClassLoader) for a discussion about the format of the property files and the way to determine the candidat files to load. Note that those methods are different in the way to locate the candidat files. This method searches in the provided path (dir parameter), while the referred method searches using the getResource method of the provided ClassLoader.

Parameters:
family - The family name (or base name) which is used to search actual properties files.
dir - The search path to locate the property files
Throws:
java.net.MalformedURLException
See Also:
ResourceBundle

addResourceFamily

public static void addResourceFamily(java.lang.String family,
                                     java.lang.ClassLoader loader,
                                     java.lang.String callerName)

Adds an additional family of resource files containing some translations. The search path is determined by the getResource method from the provided ClassLoader.

This method is identical to addResourceFamily(String, ClassLoader), except that it adds a callerName parameter to show in the log.

See addResourceFamily(String, ClassLoader) for a discussion about the format of the property files andthe way to determine the candidat files to load.

Parameters:
family - The family name (or base name) which is used to search actual properties files.
loader - A ClassLoader which is able to find a property file matching the specified family name and the preferred locales
callerName - A symbolic name given to the caller of this method, to show it in the log if there is an error
See Also:
ResourceBundle

addResourceFamily

public static void addResourceFamily(java.lang.String family,
                                     java.lang.String callerName)

Adds an additional family of resource files containing some translations.

This method is identical to addResourceFamily(String, ClassLoader, String), except that it uses the caller's class loader.

See addResourceFamily(String, ClassLoader) for a discussion about the format of the property files and the way to determine the candidat files to load.

Parameters:
family - The family name (or base name) which is used to search actual properties files.
callerName - A symbolic name given to the caller of this method, to show it in the log if there is an error. This is only used to show something meaningful in the log, so you can use any string
See Also:
ResourceBundle

getPreferredLocales

public static java.util.ArrayList getPreferredLocales()
Returns an ArrayList containing the ordered list of prefered Locales Each element of the ArrayList is a Locale object.

Returns:
an ArrayList containing the ordered list of prefered Locales Each element of the ArrayList is a Locale object.

setPreferredLocales

public static void setPreferredLocales(java.util.ArrayList preferredLocalesList)

Sets the ordered list of preferred locales. Each element of the ArrayList is a Locale object.

Note that calling this method does not load any translation, it just adds the language to the preferred locales list, so this method must be always called before the translations are loaded using the addResourceFamily() methods.

It there was any language in the preferred locale list, the language and its associated translations are deleted.

Parameters:
preferredLocalesList - an ArrayList containing Locale objects. The ArrayList represents an ordered list of preferred locales

addLocale

public static void addLocale(java.util.Locale lang)
Adds a Locale at the end of the ordered list of preferred locales. Note that calling this method does not load any translation, it just adds the language to the preferred locales list, so this method must be always called before the translations are loaded using the addResourceFamily() methods.

Parameters:
lang - A Locale object specifying the locale to add

removeLocale

public static boolean removeLocale(java.util.Locale lang)
Removes the specified Locale from the list of preferred locales and the translations associated with this locale.

Parameters:
lang - A Locale object specifying the locale to remove
Returns:
True if the locale was in the preferred locales list, false otherwise

removeResources

public static void removeResources()
Cleans the translation tables (removes all the translations from memory).


hasLocales

public static boolean hasLocales()
Checks if some locale has been added to the preferred locales list, which is necessary before loading any translation because only the translations for the preferred locales are loaded.

Returns:

getBaseLanguage

public static java.lang.String getBaseLanguage()
Gets the base language, the language considered the origin of translations, which will be (possibly) stored in a property file without language suffix (ie: text.properties instead of text_es.properties).


setBaseLanguage

public static void setBaseLanguage(java.lang.String lang)
Sets the base language, the language considered the origin of translations, which will be (possibly) stored in a property file without language suffix (ie: text.properties instead of text_es.properties).

Parameters:
lang - The base language to be set

getResourceFile

public static java.io.File getResourceFile(java.lang.String dir,
                                           java.lang.String file_name)
Returns:
A Vector containing the available languages. Each element is an String object