org.gvsig.i18n

Class Messages

java.lang.Object

org.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:

• Add some locale to the prefered locales list: Messages.addLocale(new Locale("es"))
• Add some resource file containing translations: Messages.addResourceFamily("text", new File("."))
• And finaly getText can be used: Messages.getText("aceptar")

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.

Constructor Summary

Constructors

Constructor and Description
Messages()

Method Summary

Modifier and Type	Method and Description
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 folder) 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.util.Properties	getAllTexts(java.util.Locale lang)
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.Locale	getCurrentLocale()
static java.util.List	getNotTranslatedKeys()
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.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, boolean log) 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 java.util.Properties	getTranslations(java.util.Locale locale)
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.
protected static java.util.Set	keySet(java.util.Locale lang)
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	setCurrentLocale(java.util.Locale locale) Deprecated. use setCurrentLocale(Locale locale, Locale alternatives[]) or LocaleManager.setCurrentLocale
static void	setCurrentLocale(java.util.Locale locale, java.util.Locale[] alternatives)
static void	setPreferredLocales(java.util.ArrayList preferredLocalesList) Sets the ordered list of preferred locales.
protected static int	size(java.util.Locale lang) The number of translation keys which have been loaded till now (In other words: the number of available translation strings).
static java.lang.String	translate(java.lang.String message)
static java.lang.String	translate(java.lang.String message, java.lang.String[] args)

Methods inherited from class java.lang.Object

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

Constructor Detail

Messages

public Messages()

Method Detail

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)

translate

public static java.lang.String translate(java.lang.String message,
                                         java.lang.String[] args)

translate

public static java.lang.String translate(java.lang.String message)

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)

getText

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

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.

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 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.

For example:

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 folder)
                              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.

folder - 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

getCurrentLocale

public static java.util.Locale getCurrentLocale()

setCurrentLocale

public static void setCurrentLocale(java.util.Locale locale)

Deprecated. use setCurrentLocale(Locale locale, Locale alternatives[]) or LocaleManager.setCurrentLocale

Parameters:

locale -

setCurrentLocale

public static void setCurrentLocale(java.util.Locale locale,
                                    java.util.Locale[] alternatives)

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).

size

protected static int size(java.util.Locale lang)

The number of translation keys which have been loaded till now (In other words: the number of available translation strings).

Parameters:

lang - The language for which we want to know the number of translation keys

Returns:

The number of translation keys for the provided language.

keySet

protected static java.util.Set keySet(java.util.Locale lang)

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).

Returns:

the base language name

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

getAllTexts

public static java.util.Properties getAllTexts(java.util.Locale lang)

getTranslations

public static java.util.Properties getTranslations(java.util.Locale locale)

getNotTranslatedKeys

public static java.util.List getNotTranslatedKeys()