Package org.javarosa.core.services.locale

Class Localizer

java.lang.Object
org.javarosa.core.services.locale.Localizer
All Implemented Interfaces:
Externalizable
public class Localizer
extends Object
implements Externalizable
The Localizer object maintains mappings for locale ID's and Object ID's to the String values associated with them in different locales.
Author:
Drew Roos/Clayton Sims

  • Constructor Details

    • Localizer

      public Localizer()
      Default constructor. Disables all fallback modes.

    • Localizer

      public Localizer​(boolean fallbackDefaultLocale, boolean fallbackDefaultForm)
      Full constructor.
      Parameters:
      fallbackDefaultLocale - If true, search the default locale when no translation for a particular text handle is found in the current locale.
      fallbackDefaultForm - If true, search the default text form when no translation is available for the specified text form ('long', 'short', etc.). Note: form is specified by appending ';[form]' onto the text ID.

  • Method Details

    • equals

      public boolean equals​(Object o)
      Overrides:
      equals in class Object

    • getFallbackLocale

      public boolean getFallbackLocale()
      Get default locale fallback mode
      Returns:
      default locale fallback mode

    • getFallbackForm

      public boolean getFallbackForm()
      Get default form fallback mode
      Returns:
      default form fallback mode

    • addAvailableLocale

      public boolean addAvailableLocale​(String locale)
      Create a new locale (with no mappings). Do nothing if the locale is already defined.
      Parameters:
      locale - Locale to add. Must not be null.
      Returns:
      True if the locale was not already defined.
      Throws:
      NullPointerException - if locale is null

    • getAvailableLocales

      public String[] getAvailableLocales()
      Get a list of defined locales.
      Returns:
      Array of defined locales, in order they were created.

    • hasLocale

      public boolean hasLocale​(String locale)
      Get whether a locale is defined. The locale need not have any mappings.
      Parameters:
      locale - Locale
      Returns:
      Whether the locale is defined. False if null

    • getNextLocale

      public String getNextLocale()
      Return the next locale in order, for cycling through locales.
      Returns:
      Next locale following the current locale (if the current locale is the last, cycle back to the beginning). If the current locale is not set, return the default locale. If the default locale is not set, return null.

    • getLocale

      public String getLocale()
      Get the current locale.
      Returns:
      Current locale.

    • setLocale

      public void setLocale​(String currentLocale)
      Set the current locale. The locale must be defined. Will notify all registered ILocalizables of the change in locale.
      Parameters:
      currentLocale - Locale. Must be defined and not null.
      Throws:
      UnregisteredLocaleException - If locale is null or not defined.

    • getDefaultLocale

      public String getDefaultLocale()
      Get the default locale.
      Returns:
      Default locale.

    • setDefaultLocale

      public void setDefaultLocale​(String defaultLocale)
      Set the default locale. The locale must be defined.
      Parameters:
      defaultLocale - Default locale. Must be defined. May be null, in which case there will be no default locale.
      Throws:
      UnregisteredLocaleException - If locale is not defined.

    • setToDefault

      public void setToDefault()
      Set the current locale to the default locale. The default locale must be set.
      Throws:
      IllegalStateException - If default locale is not set.

    • registerLocaleResource

      public void registerLocaleResource​(String locale, LocaleDataSource resource)
      Registers a resource file as a source of locale data for the specified locale.
      Parameters:
      locale - The locale of the definitions provided.
      resource - A LocaleDataSource containing string data for the locale provided
      Throws:
      NullPointerException - if resource or locale are null

    • getLocaleData

      public OrderedMap<String,​String> getLocaleData​(String locale)
      Get the set of mappings for a locale.
      Parameters:
      locale - Locale

    • getLocaleMap

      public OrderedMap<String,​String> getLocaleMap​(String locale)
      Get the mappings for a locale, but throw an exception if locale is not defined.
      Parameters:
      locale - Locale
      Returns:
      Text mappings for locale.
      Throws:
      UnregisteredLocaleException - If locale is not defined or null.

    • hasMapping

      public boolean hasMapping​(String locale, String textID)
      Determine whether a locale has a mapping for a given text handle. Only tests the specified locale and form; does not fallback to any default locale or text form.
      Parameters:
      locale - Locale. Must be defined and not null.
      textID - Text handle.
      Returns:
      True if a mapping exists for the text handle in the given locale.
      Throws:
      UnregisteredLocaleException - If locale is not defined.

    • destroyLocale

      public boolean destroyLocale​(String locale)
      Undefine a locale and remove all its data. Cannot be called on the current locale. If called on the default locale, no default locale will be set afterward.
      Parameters:
      locale - Locale to remove. Must not be null. Need not be defined. Must not be the current locale.
      Returns:
      Whether the locale existed in the first place.
      Throws:
      IllegalArgumentException - If locale is the current locale.
      NullPointerException - if locale is null

    • getText

      public String getText​(String textID)
      Retrieve the localized text for a text handle in the current locale. See getText(String, String) for details.
      Parameters:
      textID - Text handle (text ID appended with optional text form). Must not be null.
      Returns:
      Localized text. If no text is found after using all fallbacks, return null.
      Throws:
      UnregisteredLocaleException - If current locale is not set.
      NullPointerException - if textID is null

    • getText

      public String getText​(String textID, String[] args)
      Retrieve the localized text for a text handle in the current locale. See getText(String, String) for details.
      Parameters:
      textID - Text handle (text ID appended with optional text form). Must not be null.
      args - arguments for string variables.
      Returns:
      Localized text
      Throws:
      UnregisteredLocaleException - If current locale is not set.
      NullPointerException - if textID is null
      NoLocalizedTextException - If there is no text for the specified id

    • getText

      public String getText​(String textID, HashMap<String,​String> args)
      Retrieve the localized text for a text handle in the current locale. See getText(String, String) for details.
      Parameters:
      textID - Text handle (text ID appended with optional text form). Must not be null.
      args - arguments for string variables.
      Returns:
      Localized text
      Throws:
      UnregisteredLocaleException - If current locale is not set.
      NullPointerException - if textID is null
      NoLocalizedTextException - If there is no text for the specified id

    • getLocalizedText

      public String getLocalizedText​(String textID)
      Retrieve localized text for a text handle in the current locale. Like getText(String), however throws exception if no localized text is found.
      Parameters:
      textID - Text handle (text ID appended with optional text form). Must not be null.
      Returns:
      Localized text
      Throws:
      NoLocalizedTextException - If there is no text for the specified id
      UnregisteredLocaleException - If current locale is not set
      NullPointerException - if textID is null

    • getText

      public String getText​(String textID, String locale)
      Retrieve the localized text for a text handle in the given locale. If no mapping is found initially, then, depending on enabled fallback modes, other places will be searched until a mapping is found.

      The search order is thus: 1) Specified locale, specified text form 2) Specified locale, default text form 3) Default locale, specified text form 4) Default locale, default text form

      (1) and (3) are only searched if a text form ('long', 'short', etc.) is specified. If a text form is specified, (2) and (4) are only searched if default-form-fallback mode is enabled. (3) and (4) are only searched if default-locale-fallback mode is enabled. It is not an error in this situation if no default locale is set; (3) and (4) will simply not be searched.

      Parameters:
      textID - Text handle (text ID appended with optional text form). Must not be null.
      locale - Locale. Must be defined and not null.
      Returns:
      Localized text. If no text is found after using all fallbacks, return null.
      Throws:
      UnregisteredLocaleException - If the locale is not defined or null.
      NullPointerException - if textID is null

    • getRawText

      public String getRawText​(String locale, String textID)
      Get text for locale and exact text ID only, not using any fallbacks.

      NOTE: This call will only return the full compliment of available strings if and only if the requested locale is current. Otherwise it will only retrieve strings declared at runtime.

      Parameters:
      locale - Locale. Must be defined and not null.
      textID - Text handle (text ID appended with optional text form). Must not be null.
      Returns:
      Localized text. Return null if none found.
      Throws:
      UnregisteredLocaleException - If the locale is not defined or null.
      NullPointerException - if textID is null

    • registerLocalizable

      public void registerLocalizable​(Localizable l)
      Register a Localizable to receive updates when the locale is changed. If the Localizable is already registered, nothing happens. If a locale is currently set, the new Localizable will receive an immediate 'locale changed' event.
      Parameters:
      l - Localizable to register.

    • unregisterLocalizable

      public void unregisterLocalizable​(Localizable l)
      Unregister an Localizable from receiving locale change updates. No effect if the Localizable was never registered in the first place.
      Parameters:
      l - Localizable to unregister.

    • unregisterAll

      public void unregisterAll()
      Unregister all ILocalizables.

    • getArgs

      public static List<String> getArgs​(String text)

    • processArguments

      public static String processArguments​(String text, HashMap<String,​String> args)

    • processArguments

      public static String processArguments​(String text, String[] args)

    • processArguments

      public static String processArguments​(String text, String[] args, int currentArg)

    • clearArguments

      public static String clearArguments​(String text)

    • readExternal

      public void readExternal​(DataInputStream dis, PrototypeFactory pf) throws IOException, DeserializationException
      Reads the object from a stream.
      Specified by:
      readExternal in interface Externalizable
      Throws:
      IOException
      DeserializationException

    • writeExternal

      public void writeExternal​(DataOutputStream dos) throws IOException
      Writes the object to a stream.
      Specified by:
      writeExternal in interface Externalizable
      Throws:
      IOException