Package org.sm.smtools.application.util

Enum I18NL10N

java.lang.Object

java.lang.Enum<I18NL10N>

org.sm.smtools.application.util.I18NL10N

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<I18NL10N>, java.lang.constant.Constable

public enum I18NL10N
extends java.lang.Enum<I18NL10N>

The I18NL10N class provides a mechanism for implementing a multi-lingual interface through internationalisation (I18N) and localisation (L10N).

The idea behind this class is that, whenever a String locale is needed, it is replaced by a lookup in the database that gives a translation to the currently selected locale. The database is based on keys and values: the keys provide the lookup-mechanism (which is case-insensitive), whereas the values represent the translations.

When an application is starting, the database (a 'properties' file) containing the selected locale should be loaded using the load(String) or load(InputStream) methods. Note that, as opposed to a ResourceBundle, the I18NL10N class can easily handle different file locations. Use the getFilename(String) and getFilename(String,String) methods to specify a file location and an optional locale, for example:

   I18NL10N.kINSTANCE.load(I18NL10N.kINSTANCE.getFilename("locales-",I18NL10N.kINSTANCE.kLocaleBritishEnglish));
 

Translations are performed by the following lookup:

   String translation = I18NL10N.kINSTANCE.translate(key,parameters);
 

The optional parameters are specified in the keys using (^i) with i the number of the parameter. In order to get the caret itself, it should be escaped by writing it twice (^^).

Some examples

The file should have the following structure: each line should contain at most one (key,value) pair. They are specified as:

   key=value
 

Blank lines are allowed; comments are preceeded by a # character.

• Consider the following database file:
  • my.First.Key=my first value
  • my.Second.Key=my ^1 value
• The following translations demonstrate its usage:
  • I18NL10N.kINSTANCE.translate("my.First.Key") will result in "my first value".
  • I18NL10N.kINSTANCE.translate("my.Second.Key","second") will result in "my second value".
• A GUI is typically constructed with statements like the following one:
  
  • JLabel label = new JLabel(I18NL10N.kINSTANCE.translate("labelKey","parameter 1",...,"parameter N"));

Note that this class cannot be subclassed!

Version:

07/03/2020

Author:

Sven Maerivoet

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

java.lang.Enum.EnumDesc<E extends java.lang.Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
kINSTANCE	The singleton instance.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	kLocaleAmericanEnglish	Useful constant for specifying an American English locale.
static java.lang.String	kLocaleBritishEnglish	Useful constant for specifying a British English locale.
static java.lang.String	kLocaleDutch	Useful constant for specifying a Dutch locale.

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears the database.
java.util.Locale	getCurrentLocale()	Returns the currently used locale.
java.lang.String	getCurrentLocaleDescription()	Returns the descriptive name of the currently used locale.
java.lang.String	getCurrentLocaleName()	Returns the short BCP 47 name of the currently used locale.
java.lang.String	getFilename(java.lang.String localeFilenamePrefix)	Returns a filename based on a prefix only (the system's default locale is assumed).
java.lang.String	getFilename(java.lang.String localeFilenamePrefix, java.lang.String localeSpecifier)	Returns a filename based on a prefix and locale.
void	load(java.io.InputStream languageInputStream)	Loads a database from an InputStream.
void	load(java.lang.String localeFilename)	Loads a database from a specified file.
java.lang.String	translate(java.lang.String languageKey, java.lang.String... parameters)	Looks up a key in the database and retrieves its translation.
java.lang.Integer	translateMnemonic(java.lang.String mnemonic)	Returns the KeyEvent code associated with the specified mnemonic.
static I18NL10N	valueOf(java.lang.String name)	Returns the enum constant of this type with the specified name.
static I18NL10N[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

kINSTANCE

public static final I18NL10N kINSTANCE

The singleton instance.

Field Details

kLocaleDutch

public static final java.lang.String kLocaleDutch

Useful constant for specifying a Dutch locale.

See Also:

Constant Field Values

kLocaleBritishEnglish

public static final java.lang.String kLocaleBritishEnglish

Useful constant for specifying a British English locale.

kLocaleAmericanEnglish

public static final java.lang.String kLocaleAmericanEnglish

Useful constant for specifying an American English locale.

Method Details

values

public static I18NL10N[] values()

Returns an array containing the constants of this enum type, in the order they are declared.

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static I18NL10N valueOf(java.lang.String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

java.lang.IllegalArgumentException - if this enum type has no constant with the specified name

java.lang.NullPointerException - if the argument is null

getFilename

public java.lang.String getFilename(java.lang.String localeFilenamePrefix,
java.lang.String localeSpecifier)
                             throws java.io.FileNotFoundException

Returns a filename based on a prefix and locale.

The system's default locale is used if null is assigned to the localeSpecifier.

Parameters:

localeFilenamePrefix - the path and prefix name of the file containing the database

localeSpecifier - the locale to be used

Returns:

a filename based on a prefix and locale

Throws:

java.io.FileNotFoundException - if the file containing the database could not be opened or the locale was not found

See Also:

getFilename(String), load(String), load(InputStream)

getFilename

public java.lang.String getFilename(java.lang.String localeFilenamePrefix)
                             throws java.io.FileNotFoundException

Returns a filename based on a prefix only (the system's default locale is assumed).

Parameters:

localeFilenamePrefix - the path and prefix name of the file containing the database

Returns:

a filename based on a prefix and the system's default locale

Throws:

java.io.FileNotFoundException - if the file containing the database could not be opened or the locale was not found

See Also:

getFilename(String,String), load(String), load(InputStream)

load

public void load(java.lang.String localeFilename)
          throws java.io.FileNotFoundException

Loads a database from a specified file.

Note: all existing keys will be overwritten with the new values.

Parameters:

localeFilename - the name of the file containing the database

Throws:

java.io.FileNotFoundException - if the file containing the database could not be opened

See Also:

getFilename(String), getFilename(String,String), load(InputStream)

load

public void load(java.io.InputStream languageInputStream)
          throws FileReadException

Loads a database from an InputStream.

Note: all existing keys will be overwritten with the new values.

Parameters:

languageInputStream - the InputStream containing the database

Throws:

FileReadException - if an I/O error occurs during reading from the specified InputStream

See Also:

getFilename(String), getFilename(String,String), load(String)

clear

public void clear()

Clears the database.

getCurrentLocaleDescription

public java.lang.String getCurrentLocaleDescription()

Returns the descriptive name of the currently used locale.

Returns:

the descriptive name of the currently used locale

getCurrentLocaleName

public java.lang.String getCurrentLocaleName()

Returns the short BCP 47 name of the currently used locale.

This refers to the IETF's Best Current Practice, see also http://en.wikipedia.org/wiki/IETF_language_tag.

Returns:

the short BCP 47 name of the currently used locale

getCurrentLocale

public java.util.Locale getCurrentLocale()

Returns the currently used locale.

Returns:

the currently used locale

translate

public java.lang.String translate(java.lang.String languageKey,
java.lang.String... parameters)

Looks up a key in the database and retrieves its translation.

Note that when the key is not found, an empty string ("") is returned instead of null.

Parameters are identified with a caret ^ (the caret itself is escaped as ^^). Any redundant specified parameters are ignored.

Parameters:

languageKey - the key to search for in the database

parameters - the optional parameters to substitute in the translated value

Returns:

the value corresponding to the languageKey

translateMnemonic

public java.lang.Integer translateMnemonic(java.lang.String mnemonic)

Returns the KeyEvent code associated with the specified mnemonic.

A mnemonic consists of a single character; this method does however relaxes this assumption, as it allows for a complete String to be specified (only the first character is considered). So its convenient for the caller to pass a key as parameter to this method.

Parameters:

mnemonic - the mnemonic to retrieve the KeyEvent code from

Returns:

the KeyEvent code associated with the specified mnemonic (null if the mnemonic was empty)