APIdia Launch Partner
Top Description Fields Constructors Methods
com.badlogic.gdx.utils

public Class I18NBundle

extends Object
Class Inheritance
Imports
java.io.IOException, .Reader, java.util.ArrayList, .LinkedHashSet, .List, .Locale, .MissingResourceException, .Set, com.badlogic.gdx.files.FileHandle
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. Examples 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.
Author
davebaol
See Also
PropertiesUtils

Field Summary

Modifier and TypeField and Description
private static final String
DEFAULT_ENCODING

private static boolean
exceptionOnMissingKey

private TextFormatter
formatter

The formatter used for argument replacement.

private Locale
locale

The locale for this bundle.

private I18NBundle
parent

The parent of this I18NBundle that is used if this bundle doesn't include the requested resource.

private ObjectMap<String, String>
properties

The properties for this bundle.

private static boolean
simpleFormatter

Constructor Summary

AccessConstructor and Description
public
I18NBundle()

Method Summary

Modifier and TypeMethod and Description
private static boolean
checkFileExistence(FileHandle fh)

public static I18NBundle

Returns:

a bundle for the given base file handle and the default locale
createBundle(FileHandle
the file handle to the base of the bundle
baseFileHandle)

Creates a new bundle using the specified baseFileHandle, the default locale and the default encoding "UTF-8".

public static I18NBundle

Returns:

a bundle for the given base file handle and locale
createBundle(FileHandle
the file handle to the base of the bundle
baseFileHandle, Locale
the locale for which a bundle is desired
locale)

Creates a new bundle using the specified baseFileHandle and locale; the default encoding "UTF-8" is used.

public static I18NBundle

Returns:

a bundle for the given base file handle and locale
createBundle(FileHandle
the file handle to the base of the bundle
baseFileHandle, String
the character encoding
encoding)

Creates a new bundle using the specified baseFileHandle and encoding; the default locale is used.

public static I18NBundle

Returns:

a bundle for the given base file handle and locale
createBundle(FileHandle
the file handle to the base of the bundle
baseFileHandle, Locale
the locale for which a bundle is desired
locale, String
the character encoding
encoding)

Creates a new bundle using the specified baseFileHandle, locale and encoding.

private static I18NBundle
createBundleImpl(FileHandle baseFileHandle, Locale locale, String encoding)

public void
debug(String placeholder)

Sets the value of all localized strings to String placeholder so hardcoded, unlocalized values can be easily spotted.

public String

Returns:

the string for the given key formatted with the given arguments
format(String
the key for the desired string
key, Object...
the arguments to be replaced in the string associated to the given key.
args)

Gets the string with the specified key from this bundle or one of its parent after replacing the given arguments if they occur.

public String

Returns:

the string for the given key or the key surrounded by ??? if it cannot be found and getExceptionOnMissingKey() returns false
get(String
the key for the desired string
key)

Gets a string for the given key from this bundle or one of its parents.

private static List<Locale>

Returns:

a List of candidate Locales for the given locale
getCandidateLocales(Locale
the locale for which a resource bundle is desired
locale)

Returns a List of Locales as candidate locales for the given locale.

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.

private static Locale

Returns:

a Locale for the fallback search, or null if no further fallback search is needed.
getFallbackLocale(Locale
the Locale for which createBundle has been unable to find any resource bundles (except for the base bundle)
locale)

Returns a Locale to be used as a fallback locale for further bundle searches by the createBundle factory method.

public Locale

Returns:

the locale of this bundle
getLocale()

Returns the locale of this bundle.

public static boolean
getSimpleFormatter()

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

public Set<String>

Returns:

a key set of loaded properties. Never null, might be an empty set
keys()

Gets a key set of loaded properties.

protected void
load(Reader
the reader
reader)

Load the properties from the specified reader.

private static I18NBundle
loadBundle(FileHandle baseFileHandle, String encoding, Locale targetLocale)

private static I18NBundle
loadBundleChain(FileHandle baseFileHandle, String encoding, List<Locale> candidateLocales, int candidateIndex, I18NBundle baseBundle)

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.

private void
setLocale(Locale locale)

Sets the bundle locale.

public static void
setSimpleFormatter(boolean enabled)

Sets the flag indicating whether to use the simplified message pattern.

private static FileHandle

Returns:

the file handle for the bundle
toFileHandle(FileHandle
the file handle to the base of the bundle
baseFileHandle, Locale
the locale for which a resource bundle should be loaded
locale)

Converts the given baseFileHandle and locale to the corresponding file handle.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

DEFAULT_ENCODINGback to summary
private static final String DEFAULT_ENCODING
exceptionOnMissingKeyback to summary
private static boolean exceptionOnMissingKey
formatterback to summary
private TextFormatter formatter

The formatter used for argument replacement.

localeback to summary
private Locale locale

The locale for this bundle.

parentback to summary
private I18NBundle parent

The parent of this I18NBundle that is used if this bundle doesn't include the requested resource.

propertiesback to summary
private ObjectMap<String, String> properties

The properties for this bundle.

simpleFormatterback to summary
private static boolean simpleFormatter

Constructor Detail

I18NBundleback to summary
public I18NBundle()

Method Detail

checkFileExistenceback to summary
private static boolean checkFileExistence(FileHandle fh)
createBundleback to summary
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:FileHandle

the file handle to the base of the bundle

Returns:I18NBundle

a bundle for the given base file handle and the default locale

Exceptions
NullPointerException:
if baseFileHandle is null
MissingResourceException:
if no bundle for the specified base file handle can be found
createBundleback to summary
public static I18NBundle createBundle(FileHandle baseFileHandle, Locale locale)

Creates a new bundle using the specified baseFileHandle and locale; the default encoding "UTF-8" is used.

Parameters
baseFileHandle:FileHandle

the file handle to the base of the bundle

locale:Locale

the locale for which a bundle is desired

Returns:I18NBundle

a bundle for the given base file handle and locale

Exceptions
NullPointerException:
if baseFileHandle or locale is null
MissingResourceException:
if no bundle for the specified base file handle can be found
createBundleback to summary
public static I18NBundle createBundle(FileHandle baseFileHandle, String encoding)

Creates a new bundle using the specified baseFileHandle and encoding; the default locale is used.

Parameters
baseFileHandle:FileHandle

the file handle to the base of the bundle

encoding:String

the character encoding

Returns:I18NBundle

a bundle for the given base file handle and locale

Exceptions
NullPointerException:
if baseFileHandle or encoding is null
MissingResourceException:
if no bundle for the specified base file handle can be found
createBundleback to summary
public static I18NBundle createBundle(FileHandle baseFileHandle, Locale locale, String encoding)

Creates a new bundle using the specified baseFileHandle, locale and encoding.

Parameters
baseFileHandle:FileHandle

the file handle to the base of the bundle

locale:Locale

the locale for which a bundle is desired

encoding:String

the character encoding

Returns:I18NBundle

a bundle for the given base file handle and locale

Exceptions
NullPointerException:
if baseFileHandle, locale or encoding is null
MissingResourceException:
if no bundle for the specified base file handle can be found
createBundleImplback to summary
private static I18NBundle createBundleImpl(FileHandle baseFileHandle, Locale locale, String encoding)
debugback to summary
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.

formatback to summary
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:String

the key for the desired string

args:Object[]

the arguments to be replaced in the string associated to the given key.

Returns:String

the string for the given key formatted with the given arguments

Exceptions
NullPointerException:
if key is null
MissingResourceException:
if no string for the given key can be found
getback to summary
public String get(String key)

Gets a string for the given key from this bundle or one of its parents.

Parameters
key:String

the key for the desired string

Returns:String

the string for the given key or the key surrounded by ??? if it cannot be found and getExceptionOnMissingKey() returns false

Exceptions
NullPointerException:
if key is null
MissingResourceException:
if no string for the given key can be found and getExceptionOnMissingKey() returns true
getCandidateLocalesback to summary
private static List<Locale> getCandidateLocales(Locale locale)

Returns a List of Locales as candidate locales for the given locale. This method is called by the createBundle factory method each time the factory method tries finding a resource bundle for a target Locale.

The sequence of the candidate locales also corresponds to the runtime resource lookup path (also known as the parent chain), if the corresponding resource bundles for the candidate locales exist and their parents are not defined by loaded resource bundles themselves. The last element of the list is always the root locale, meaning that the base bundle is the terminal of the parent chain.

If the given locale is equal to Locale.ROOT (the root locale), a List containing only the root Locale is returned. In this case, the createBundle factory method loads only the base bundle as the resulting resource bundle.

This implementation returns a List containing Locales in the following sequence: 

    Locale(language, country, variant)
    Locale(language, country)
    Locale(language)
    Locale.ROOT
where language, country and variant are the language, country and variant values of the given locale, respectively. Locales where the final component values are empty strings are omitted.

For example, if the given base name is "Messages" and the given locale is Locale("ja", "", "XX"), then a List of Locales: 

    Locale("ja", "", "XX")
    Locale("ja")
    Locale.ROOT
is returned. And if the resource bundles for the "ja" and "" Locales are found, then the runtime resource lookup path (parent chain) is: 
    Messages_ja -> Messages
Parameters
locale:Locale

the locale for which a resource bundle is desired

Returns:List<Locale>

a List of candidate Locales for the given locale

Exceptions
NullPointerException:
if locale is null
getExceptionOnMissingKeyback to summary
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.

getFallbackLocaleback to summary
private static Locale getFallbackLocale(Locale locale)

Returns a Locale to be used as a fallback locale for further bundle searches by the createBundle factory method. This method is called from the factory method every time when no resulting bundle has been found for baseFileHandler and locale, where locale is either the parameter for createBundle or the previous fallback locale returned by this method.

This method returns the default Locale if the given locale isn't the default one. Otherwise, null is returned.

Parameters
locale:Locale

the Locale for which createBundle has been unable to find any resource bundles (except for the base bundle)

Returns:Locale

a Locale for the fallback search, or null if no further fallback search is needed.

Exceptions
NullPointerException:
if locale is null
getLocaleback to summary
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:Locale

the locale of this bundle

getSimpleFormatterback to summary
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.

keysback to summary
public Set<String> keys()

Gets a key set of loaded properties. Keys will be copied into a new set and returned.

Returns:Set<String>

a key set of loaded properties. Never null, might be an empty set

loadback to summary
protected void load(Reader reader) throws IOException

Load the properties from the specified reader.

Parameters
reader:Reader

the reader

Exceptions
IOException:
if an error occurred when reading from the input stream.
loadBundleback to summary
private static I18NBundle loadBundle(FileHandle baseFileHandle, String encoding, Locale targetLocale)
loadBundleChainback to summary
private static I18NBundle loadBundleChain(FileHandle baseFileHandle, String encoding, List<Locale> candidateLocales, int candidateIndex, I18NBundle baseBundle)
setExceptionOnMissingKeyback to summary
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.

setLocaleback to summary
private void setLocale(Locale locale)

Sets the bundle locale. This method is private because a bundle can't change the locale during its life.

setSimpleFormatterback to summary
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.

toFileHandleback to summary
private static FileHandle toFileHandle(FileHandle baseFileHandle, Locale locale)

Converts the given baseFileHandle and locale to the corresponding file handle.

This implementation returns the baseFileHandle's sibling with following value: 

baseFileHandle.name() + "_" + language + "_" + country + "_" + variant + ".properties"
where language, country and variant are the language, country and variant values of locale, respectively. Final component values that are empty Strings are omitted along with the preceding '_'. If all of the values are empty strings, then baseFileHandle.name() is returned with ".properties" appended.
Parameters
baseFileHandle:FileHandle

the file handle to the base of the bundle

locale:Locale

the locale for which a resource bundle should be loaded

Returns:FileHandle

the file handle for the bundle

Exceptions
NullPointerException:
if baseFileHandle or locale is null