Package com.badlogic.gdx.utils

Class I18NBundle

  • public class I18NBundle
extends java.lang.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:
    PropertiesUtils

    • Constructor Summary

      Constructors 
      Constructor Description
      I18NBundle()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static I18NBundle createBundle​(FileHandle baseFileHandle)
      Creates a new bundle using the specified baseFileHandle, the default locale and the default encoding "UTF-8".
      static I18NBundle createBundle​(FileHandle baseFileHandle, java.lang.String encoding)
      Creates a new bundle using the specified baseFileHandle and encoding; the default locale is used.
      static I18NBundle createBundle​(FileHandle baseFileHandle, java.util.Locale locale)
      Creates a new bundle using the specified baseFileHandle and locale; the default encoding "UTF-8" is used.
      static I18NBundle createBundle​(FileHandle baseFileHandle, java.util.Locale locale, java.lang.String encoding)
      Creates a new bundle using the specified baseFileHandle, locale and encoding.
      void debug​(java.lang.String placeholder)
      Sets the value of all localized strings to String placeholder so hardcoded, unlocalized values can be easily spotted.
      java.lang.String format​(java.lang.String key, java.lang.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.
      java.lang.String get​(java.lang.String key)
      Gets a string for the given key from this bundle or one of its parents.
      static boolean getExceptionOnMissingKey()
      Returns the flag indicating whether to throw a MissingResourceException from the get(key) method if no string for the given key can be found.
      java.util.Locale getLocale()
      Returns the locale of this bundle.
      static boolean getSimpleFormatter()
      Returns the flag indicating whether to use the simplified message pattern syntax (default is false).
      java.util.Set<java.lang.String> keys()
      Gets a key set of loaded properties.
      protected void load​(java.io.Reader reader)
      Load the properties from the specified reader.
      static void setExceptionOnMissingKey​(boolean enabled)
      Sets the flag indicating whether to throw a MissingResourceException from the get(key) method if no string for the given key can be found.
      static void setSimpleFormatter​(boolean enabled)
      Sets the flag indicating whether to use the simplified message pattern.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • I18NBundle

        public I18NBundle()

    • Method Detail

      • getSimpleFormatter

        public static boolean getSimpleFormatter()
        Returns the flag indicating whether to use the simplified message pattern syntax (default is false). This flag is always assumed to be true on GWT backend.

      • 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. Notice that this method has no effect on the GWT backend where it's always assumed to be true.

      • getExceptionOnMissingKey

        public static boolean getExceptionOnMissingKey()
        Returns the flag indicating whether to throw a MissingResourceException from the get(key) method if no string for the given key can be found. If this flag is false the missing key surrounded by ??? is returned.

      • setExceptionOnMissingKey

        public static void setExceptionOnMissingKey​(boolean enabled)
        Sets the flag indicating whether to throw a MissingResourceException from the get(key) method if no string for the given key can be found. If this flag is false the missing key surrounded by ??? is returned.

      • createBundle

        public static I18NBundle createBundle​(FileHandle 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:
        java.lang.NullPointerException - if baseFileHandle is null
        java.util.MissingResourceException - if no bundle for the specified base file handle can be found

      • createBundle

        public static I18NBundle createBundle​(FileHandle baseFileHandle,
                                      java.util.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:
        java.lang.NullPointerException - if baseFileHandle or locale is null
        java.util.MissingResourceException - if no bundle for the specified base file handle can be found

      • createBundle

        public static I18NBundle createBundle​(FileHandle baseFileHandle,
                                      java.lang.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 character encoding
        Returns:
        a bundle for the given base file handle and locale
        Throws:
        java.lang.NullPointerException - if baseFileHandle or encoding is null
        java.util.MissingResourceException - if no bundle for the specified base file handle can be found

      • createBundle

        public static I18NBundle createBundle​(FileHandle baseFileHandle,
                                      java.util.Locale locale,
                                      java.lang.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 character encoding
        Returns:
        a bundle for the given base file handle and locale
        Throws:
        java.lang.NullPointerException - if baseFileHandle, locale or encoding is null
        java.util.MissingResourceException - if no bundle for the specified base file handle can be found

      • load

        protected void load​(java.io.Reader reader)
             throws java.io.IOException
        Load the properties from the specified reader.
        Parameters:
        reader - the reader
        Throws:
        java.io.IOException - if an error occurred when reading from the input stream.

      • getLocale

        public java.util.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 java.lang.String get​(java.lang.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 and getExceptionOnMissingKey() returns false
        Throws:
        java.lang.NullPointerException - if key is null
        java.util.MissingResourceException - if no string for the given key can be found and getExceptionOnMissingKey() returns true

      • keys

        public java.util.Set<java.lang.String> keys()
        Gets a key set of loaded properties. Keys will be copied into a new set and returned.
        Returns:
        a key set of loaded properties. Never null, might be an empty set

      • format

        public java.lang.String format​(java.lang.String key,
                               java.lang.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:
        java.lang.NullPointerException - if key is null
        java.util.MissingResourceException - if no string for the given key can be found

      • debug

        public void debug​(java.lang.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.
        Parameters:
        placeholder -