public class Messages extends 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:
Messages.addLocale(new Locale("es"))
Messages.addResourceFamily("text", new File("."))
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 and Description |
---|
Messages() |
Modifier and Type | Method and Description |
---|---|
static void |
addLocale(Locale lang)
Adds a Locale at the end of the ordered list of preferred locales.
|
static void |
addResourceFamily(String family,
ClassLoader loader)
Adds an additional family of resource files containing some translations.
|
static void |
addResourceFamily(String family,
ClassLoader loader,
String callerName)
Adds an additional family of resource files containing some translations.
|
static void |
addResourceFamily(String family,
File folder)
Adds an additional family of resource files containing some translations.
|
static void |
addResourceFamily(String family,
File[] dirList)
Adds an additional family of resource files containing some translations.
|
static void |
addResourceFamily(String family,
String callerName)
Adds an additional family of resource files containing some translations.
|
static Properties |
getAllTexts(Locale lang) |
static 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 Locale |
getCurrentLocale() |
static List |
getNotTranslatedKeys() |
static ArrayList |
getPreferredLocales()
Returns an ArrayList containing the ordered list of prefered Locales
Each element of the ArrayList is a Locale object.
|
static String |
getText(String key)
Gets the localized message associated with the provided key.
|
static String |
getText(String key,
boolean log)
Gets the localized message associated with the provided key.
|
static String |
getText(String key,
String callerName)
Gets the localized message associated with the provided key.
|
static String |
getText(String key,
String[] arguments) |
static String |
getText(String key,
String[] arguments,
boolean log) |
static String |
getText(String key,
String[] arguments,
String callerName) |
static String |
getText(String key,
String[] arguments,
String callerName,
boolean log) |
static String |
getText(String key,
String callerName,
boolean log)
Gets the localized message associated with the provided key.
|
static Properties |
getTranslations(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 Set |
keySet(Locale lang) |
static boolean |
removeLocale(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(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(Locale locale)
Deprecated.
use setCurrentLocale(Locale locale, Locale alternatives[]) or LocaleManager.setCurrentLocale
|
static void |
setCurrentLocale(Locale locale,
Locale[] alternatives) |
static void |
setPreferredLocales(ArrayList preferredLocalesList)
Sets the ordered list of preferred locales.
|
protected static int |
size(Locale lang)
The number of translation keys which have been loaded till now
(In other words: the number of available translation strings).
|
static String |
translate(String message) |
static String |
translate(String message,
String[] args) |
public static String getText(String key, 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.
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 foundpublic static String getText(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.
key
- An String which identifies the translation that we want to get.public static String getText(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.
key
- An String which identifies the translation that we want
to get.log
- Determines whether log a key failure or notpublic static String getText(String key, 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.
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 foundlog
- Determines whether log a key failure or notpublic static String getText(String key, String[] arguments, String callerName, boolean log)
public static void addResourceFamily(String family, 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.
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 localespublic static void addResourceFamily(String family, File[] dirList) throws 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.
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 filesMalformedURLException
public static void addResourceFamily(String family, File folder) throws 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.
family
- The family name (or base name) which is used to search
actual properties files.folder
- The search path to locate the property filesMalformedURLException
public static void addResourceFamily(String family, ClassLoader loader, 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.
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 localescallerName
- A symbolic name given to the caller of this method, to
show it in the log if there is an errorpublic static void addResourceFamily(String family, 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.
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 stringpublic static ArrayList getPreferredLocales()
public static void setPreferredLocales(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.
preferredLocalesList
- an ArrayList containing Locale objects.
The ArrayList represents an ordered list of preferred localespublic static Locale getCurrentLocale()
public static void setCurrentLocale(Locale locale)
locale
- public static void addLocale(Locale lang)
lang
- A Locale object specifying the locale to addpublic static boolean removeLocale(Locale lang)
lang
- A Locale object specifying the locale to removepublic static void removeResources()
protected static int size(Locale lang)
lang
- The language for which we want to know the number of translation keyspublic static boolean hasLocales()
public static String getBaseLanguage()
public static void setBaseLanguage(String lang)
lang
- The base language to be setpublic static Properties getAllTexts(Locale lang)
public static Properties getTranslations(Locale locale)
public static List getNotTranslatedKeys()