org.xnap.commons.i18n

Class I18n

public class I18n extends Object

Provides methods for internationalization.

To learn how message strings wrapped in one of the tr*() methods can be extracted and localized, see this tutorial.

Since: 0.9

Author: Steffen Pingel Felix Berger Tammo van Lessen

Constructor Summary
I18n(ResourceBundle bundle)
Constructs an I18n object for a resource bundle.
I18n(String baseName, Locale locale, ClassLoader loader)
Constructs an I18n object by calling I18n.
Method Summary
LocalegetLocale()
Returns the locale this instance was created with.
ResourceBundlegetResources()
Returns the current resource bundle.
static Stringmarktr(String text)
Marks text to be translated, but doesn't return the translation but text itself.
booleansetLocale(Locale locale)
Tries to load a resource bundle for the locale.
voidsetResources(ResourceBundle bundle)
Sets a resource bundle to be used for message translations.
voidsetResources(String baseName, Locale locale, ClassLoader loader)
Tries to load a resource bundle using ResourceBundle#getBundle(java.lang.String, java.util.Locale, java.lang.ClassLoader).
voidsetSourceCodeLocale(Locale locale)
Sets the locale of the text in the source code.
Stringtr(String text)
Returns text translated into the currently selected language.
Stringtr(String text, Object[] objects)
Returns text translated into the currently selected language.
Stringtr(String text, Object o1)
Convenience method that invokes (String, Object[]).
Stringtr(String text, Object o1, Object o2)
Convenience method that invokes (String, Object[]).
Stringtr(String text, Object o1, Object o2, Object o3)
Convenience method that invokes (String, Object[]).
Stringtr(String text, Object o1, Object o2, Object o3, Object o4)
Convenience method that invokes (String, Object[]).
Stringtrc(String context, String text)
Disambiguates translation keys.
Stringtrn(String text, String pluralText, long n)
Returns the plural form for n of the translation of text.
Stringtrn(String text, String pluralText, long n, Object[] objects)
Returns the plural form for n of the translation of text.
Stringtrn(String text, String pluralText, long n, Object o1)
Overloaded method that invokes (String, String, long, Object[]) passing Object arguments as an array.
Stringtrn(String text, String pluralText, long n, Object o1, Object o2)
Overloaded method that invokes (String, String, long, Object[]) passing Object arguments as an array.
Stringtrn(String text, String pluralText, long n, Object o1, Object o2, Object o3)
Overloaded method that invokes (String, String, long, Object[]) passing Object arguments as an array.
Stringtrn(String text, String pluralText, long n, Object o1, Object o2, Object o3, Object o4)
Overloaded method that invokes (String, String, long, Object[]) passing Object arguments as an array.
Stringtrnc(String context, String singularText, String pluralText, long n)
Returns the plural form for n of the translation of text.
Stringtrnc(String context, String singularText, String pluralText, long n, Object[] objects)
Returns the plural form for n of the translation of text.
Stringtrnc(String comment, String singularText, String pluralText, long n, Object obj)
Overloaded method that invokes (String, String, String, long, Object[]) passing obj arguments as an array.
Stringtrnc(String comment, String singularText, String pluralText, long n, Object obj1, Object obj2)
Overloaded method that invokes (String, String, String, long, Object[]) passing obj1 and obj2 arguments as an array.
Stringtrnc(String comment, String singularText, String pluralText, long n, Object obj1, Object obj2, Object obj3)
Overloaded method that invokes (String, String, String, long, Object[]) passing obj1, obj2 and obj3 arguments as an array.
Stringtrnc(String comment, String singularText, String pluralText, long n, Object obj1, Object obj2, Object obj3, Object obj4)
Overloaded method that invokes (String, String, String, long, Object[]) passing obj1, obj2, obj3 and obj4 arguments as an array.

Constructor Detail

I18n

public I18n(ResourceBundle bundle)
Constructs an I18n object for a resource bundle.

Parameters: bundle must not be null

Throws: NullPointerException if bundle is null

Since: 0.9

I18n

public I18n(String baseName, Locale locale, ClassLoader loader)
Constructs an I18n object by calling I18n.

Throws: MissingResourceException if the resource bundle could not be loaded NullPointerException if one of the arguments is null

Since: 0.9

Method Detail

getLocale

public Locale getLocale()
Returns the locale this instance was created with. This can be different from the locale of the resource bundle returned by getResources.

Returns: the locale or null, if this instance was directly created from a resource bundle

Since: 0.9

getResources

public ResourceBundle getResources()
Returns the current resource bundle.

Since: 0.9

marktr

public static final String marktr(String text)
Marks text to be translated, but doesn't return the translation but text itself.

Since: 0.9

setLocale

public boolean setLocale(Locale locale)
Tries to load a resource bundle for the locale.

The resource bundle is then used for message translations. Note, you have to retrieve all messages anew after a locale change in order for them to be translated to the language specified by the new locale.

Returns: false if there is not enough information for loading a new resource bundle, see setResources.

Throws: MissingResourceException if the resource bundle for locale could not be found NullPointerException if locale is null

Since: 0.9

setResources

public void setResources(ResourceBundle bundle)
Sets a resource bundle to be used for message translations.

If this is called, the possibly previously specified class loader and baseName are invalidated, since the bundle might be from a different context. Subsequent calls to setLocale won't have any effect.

Since: 0.9

setResources

public void setResources(String baseName, Locale locale, ClassLoader loader)
Tries to load a resource bundle using ResourceBundle#getBundle(java.lang.String, java.util.Locale, java.lang.ClassLoader).

Throws: MissingResourceException if the bundle could not be loaded NullPointerException if one of the arguments is null

Since: 0.9

setSourceCodeLocale

public void setSourceCodeLocale(Locale locale)
Sets the locale of the text in the source code.

Only languages that have one singular and one plural form can be used as source code locales, since I18n takes exactly these two forms as parameters.

Parameters: locale the locale

Throws: NullPointerException if locale is null

Since: 0.9

See Also: I18n

tr

public final String tr(String text)
Returns text translated into the currently selected language. Every user-visible string in the program must be wrapped into this function.

Parameters: text text to translate

Returns: the translation

Since: 0.9

tr

public final String tr(String text, Object[] objects)
Returns text translated into the currently selected language.

Occurrences of {number} placeholders in text are replaced by objects.

Invokes MessageFormat#format(java.lang.String, java.lang.Object[]).

Parameters: text text to translate objects arguments to MessageFormat.format()

Returns: the translated text

Since: 0.9

tr

public final String tr(String text, Object o1)
Convenience method that invokes (String, Object[]).

Since: 0.9

tr

public final String tr(String text, Object o1, Object o2)
Convenience method that invokes (String, Object[]).

Since: 0.9

tr

public final String tr(String text, Object o1, Object o2, Object o3)
Convenience method that invokes (String, Object[]).

Since: 0.9

tr

public final String tr(String text, Object o1, Object o2, Object o3, Object o4)
Convenience method that invokes (String, Object[]).

Since: 0.9

trc

public final String trc(String context, String text)
Disambiguates translation keys.

Parameters: context the context of the text to be translated text the ambiguous key message in the source locale

Returns: text if the locale of the underlying resource bundle equals the source code locale, the translation of comment otherwise.

Since: 0.9

See Also: setSourceCodeLocale

trn

public final String trn(String text, String pluralText, long n)
Returns the plural form for n of the translation of text.

Parameters: text the key string to be translated. pluralText the plural form of text. n value that determines the plural form

Returns: the translated text

Since: 0.9

trn

public final String trn(String text, String pluralText, long n, Object[] objects)
Returns the plural form for n of the translation of text.

Parameters: text the key string to be translated. pluralText the plural form of text. n value that determines the plural form objects object args to be formatted and substituted.

Returns: the translated text

Since: 0.9

trn

public final String trn(String text, String pluralText, long n, Object o1)
Overloaded method that invokes (String, String, long, Object[]) passing Object arguments as an array.

Since: 0.9

trn

public final String trn(String text, String pluralText, long n, Object o1, Object o2)
Overloaded method that invokes (String, String, long, Object[]) passing Object arguments as an array.

Since: 0.9

trn

public final String trn(String text, String pluralText, long n, Object o1, Object o2, Object o3)
Overloaded method that invokes (String, String, long, Object[]) passing Object arguments as an array.

Since: 0.9

trn

public final String trn(String text, String pluralText, long n, Object o1, Object o2, Object o3, Object o4)
Overloaded method that invokes (String, String, long, Object[]) passing Object arguments as an array.

Since: 0.9

trnc

public final String trnc(String context, String singularText, String pluralText, long n)
Returns the plural form for n of the translation of text.

Parameters: context the context of the message to disambiguate it when translating text the key string to be translated. pluralText the plural form of text. n value that determines the plural form

Returns: the translated text

Since: 0.9.5

trnc

public final String trnc(String context, String singularText, String pluralText, long n, Object[] objects)
Returns the plural form for n of the translation of text.

Parameters: context the context of the message to disambiguate it when translating text the key string to be translated. pluralText the plural form of text. n value that determines the plural form objects object args to be formatted and substituted.

Returns: the translated text

Since: 0.9

trnc

public final String trnc(String comment, String singularText, String pluralText, long n, Object obj)
Overloaded method that invokes (String, String, String, long, Object[]) passing obj arguments as an array.

Since: 0.9.5

trnc

public final String trnc(String comment, String singularText, String pluralText, long n, Object obj1, Object obj2)
Overloaded method that invokes (String, String, String, long, Object[]) passing obj1 and obj2 arguments as an array.

Since: 0.9.5

trnc

public final String trnc(String comment, String singularText, String pluralText, long n, Object obj1, Object obj2, Object obj3)
Overloaded method that invokes (String, String, String, long, Object[]) passing obj1, obj2 and obj3 arguments as an array.

Since: 0.9.5

trnc

public final String trnc(String comment, String singularText, String pluralText, long n, Object obj1, Object obj2, Object obj3, Object obj4)
Overloaded method that invokes (String, String, String, long, Object[]) passing obj1, obj2, obj3 and obj4 arguments as an array.

Since: 0.9.5