Package arc.util

Class I18NBundle

java.lang.Object
arc.util.I18NBundle
public class I18NBundle extends Object
A I18NBundle provides Locale-specific resources loaded from property files. A bundle contains a number of named resources, whose names and values are Strings. A bundle may have a parent bundle, and when a resource is not found in a bundle, the parent bundle is searched for the resource. If the fallback mechanism reaches the base bundle and still can't find the resource it throws a MissingResourceException.
  • All bundles for the same group of resources share a common base bundle. This base bundle acts as the root and is the last fallback in case none of its children was able to respond to a request.
  • The first level contains changes between different languages. Only the differences between a language and the language of the base bundle need to be handled by a language-specific I18NBundle.
  • The second level contains changes between different countries that use the same language. Only the differences between a country and the country of the language bundle need to be handled by a country-specific I18NBundle.
  • The third level contains changes that don't have a geographic reason (e.g. changes that where made at some point in time like PREEURO where the currency of come countries changed. The country bundle would return the current currency (Euro) and the PREEURO variant bundle would return the old currency (e.g. DM for Germany).
Examples
  • BaseName (base bundle)
  • BaseName_de (german language bundle)
  • BaseName_fr (french language bundle)
  • BaseName_de_DE (bundle with Germany specific resources in german)
  • BaseName_de_CH (bundle with Switzerland specific resources in german)
  • BaseName_fr_CH (bundle with Switzerland specific resources in french)
  • BaseName_de_DE_PREEURO (bundle with Germany specific resources in german of the time before the Euro)
  • BaseName_fr_FR_PREEURO (bundle with France specific resources in french of the time before the Euro)

It's also possible to create variants for languages or countries. This can be done by just skipping the country or language abbreviation: BaseName_us__POSIX or BaseName__DE_PREEURO. But it's not allowed to circumvent both language and country: BaseName___VARIANT is illegal.

See Also:

  • Constructor Details

    • I18NBundle

      public I18NBundle()

  • Method Details

    • getSimpleFormatter

      public static boolean getSimpleFormatter()
      Returns the flag indicating whether to use the simplified message pattern syntax (default is false).

    • setSimpleFormatter

      public static void setSimpleFormatter(boolean enabled)
      Sets the flag indicating whether to use the simplified message pattern. The flag must be set before calling the factory methods createBundle.

    • createEmptyBundle

      public static I18NBundle createEmptyBundle()
      Returns an empty bundle with no keys.

    • createBundle

      public static I18NBundle createBundle(Fi baseFileHandle)
      Creates a new bundle using the specified baseFileHandle, the default locale and the default encoding "UTF-8".
      Parameters:
      baseFileHandle - the file handle to the base of the bundle
      Returns:
      a bundle for the given base file handle and the default locale
      Throws:
      NullPointerException - if baseFileHandle is null
      MissingResourceException - if no bundle for the specified base file handle can be found

    • createBundle

      public static I18NBundle createBundle(Fi baseFileHandle, Locale locale)
      Creates a new bundle using the specified baseFileHandle and locale; the default encoding "UTF-8" is used.
      Parameters:
      baseFileHandle - the file handle to the base of the bundle
      locale - the locale for which a bundle is desired
      Returns:
      a bundle for the given base file handle and locale
      Throws:
      NullPointerException - if baseFileHandle or locale is null
      MissingResourceException - if no bundle for the specified base file handle can be found

    • createBundle

      public static I18NBundle createBundle(Fi baseFileHandle, String encoding)
      Creates a new bundle using the specified baseFileHandle and encoding; the default locale is used.
      Parameters:
      baseFileHandle - the file handle to the base of the bundle
      encoding - the charter encoding
      Returns:
      a bundle for the given base file handle and locale
      Throws:
      NullPointerException - if baseFileHandle or encoding is null
      MissingResourceException - if no bundle for the specified base file handle can be found

    • createBundle

      public static I18NBundle createBundle(Fi baseFileHandle, Locale locale, String encoding)
      Creates a new bundle using the specified baseFileHandle, locale and encoding.
      Parameters:
      baseFileHandle - the file handle to the base of the bundle
      locale - the locale for which a bundle is desired
      encoding - the charter encoding
      Returns:
      a bundle for the given base file handle and locale
      Throws:
      NullPointerException - if baseFileHandle, locale or encoding is null
      MissingResourceException - if no bundle for the specified base file handle can be found

    • getLocale

      public Locale getLocale()
      Returns the locale of this bundle. This method can be used after a call to createBundle() to determine whether the resource bundle returned really corresponds to the requested locale or is a fallback.
      Returns:
      the locale of this bundle

    • get

      public final String get(String key)
      Gets a string for the given key from this bundle or one of its parents.
      Parameters:
      key - the key for the desired string
      Returns:
      the string for the given key or the key surrounded by ??? if it cannot be found
      Throws:
      NullPointerException - if key is null

    • get

      public String get(String key, String def)
      Returns the string for this given key, or def.

    • getOrNull

      public String getOrNull(String key)

    • getNotNull

      public String getNotNull(String key)

    • getKeys

      public Iterable<String> getKeys()
      Returns all keys in this bundle. Does not check parent bundles.

    • getProperties

      public ObjectMap<String,String> getProperties()
      Returns:
      the internal property map. Can be modified.

    • setProperties

      public void setProperties(ObjectMap<String,String> properties)

    • has

      public boolean has(String key)
      Checks whether a specified key is present in this bundle.

    • format

      public String format(String key, Object... args)
      Gets the string with the specified key from this bundle or one of its parent after replacing the given arguments if they occur.
      Parameters:
      key - the key for the desired string
      args - the arguments to be replaced in the string associated to the given key.
      Returns:
      the string for the given key formatted with the given arguments
      Throws:
      NullPointerException - if key is null
      MissingResourceException - if no string for the given key can be found

    • formatString

      public String formatString(String string, Object... args)

    • formatFloat

      public String formatFloat(String key, float value, int places)
      Format, but with a number with fixed decimal places.

    • debug

      public void debug(String placeholder)
      Sets the value of all localized strings to String placeholder so hardcoded, unlocalized values can be easily spotted. The I18NBundle won't be able to reset values after calling debug and should only be using during testing.

    • getParent

      public I18NBundle getParent()
      Returns:
      the parent bundle.