Package org.gvsig.i18n

Class Messages

java.lang.Object
org.gvsig.i18n.Messages
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:

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

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

  • Constructor Details

    • Messages

      public Messages()

  • Method Details

    • getText

      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.

      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 String getText(String key, String[] arguments, String callerName)

    • translate

      public static String translate(String message, String[] args)

    • translate

      public static String translate(String message)

    • getText

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

      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 String getText(String key, String[] arguments)

    • getText

      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.

      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 String getText(String key, String[] arguments, boolean log)

    • getText

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

      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 String getText(String key, String[] arguments, String callerName, boolean log)

    • addResourceFamily

      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.

      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:

    • addResourceFamily

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

      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:
      MalformedURLException
      See Also:

    • addResourceFamily

      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.

      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:
      MalformedURLException
      See Also:

    • addResourceFamily

      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.

      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:

    • addResourceFamily

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

      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:

    • getPreferredLocales

      public static 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(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 Locale getCurrentLocale()

    • setCurrentLocale

      public static void setCurrentLocale(Locale locale)
      Parameters:
      locale -

    • setCurrentLocale

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

    • addLocale

      public static void addLocale(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(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(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 Set keySet(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 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(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 Properties getAllTexts(Locale lang)

    • getTranslations

      public static Properties getTranslations(Locale locale)

    • getNotTranslatedKeys

      public static List getNotTranslatedKeys()