com.lf.commons.i18n

Class LanguageCodes

java.lang.Object

com.lf.commons.i18n.LanguageCodes

public class LanguageCodes
extends java.lang.Object

Provides support for ISO 639-1/639-2 language codes and names in various translations.

The codes defined by this class have been extracted from the Library of Congress website http://www.loc.gov/standards/iso639-2/langhome.html with the help of an XSLT script executed by a KAT-based application. The LoC website offers the mappings from ISO 639-1 to ISO 639-2 as well as the language names in English and French. This class is a fast lightweight database for languages using efficient data caches which are installed when needed. Also the I18NFactory class provides support for a shared instance so application servers and KAT applications do not have to create multiple objects. Since the data provided here is static there is no need to have more than one single instance doing the job for you.

You can request values in each direction: get an ISO 639-2 code from ISO 639-1 and vice versa, get the language name(s) from the codes and vice versa. For populating GUI lists and comboboxes you can request containers with all available codes and names. Since there are synonyms defined for some of the ISO 639-2 codes and also for the names this class provides support for requesting these synonyms.

Another key feature of this class is the translation support. At the moment the default language for language names is English. If you like to use a different language for example while running web applications you may equip the name-related methods of this class with a locale parameter. You can pass both ISO 639-1 codes or ISO 639-2 codes for determining the desired language (e.g. "fr" for French). At the moment German and French are supported as translations. If you like the default language (English) you can pass null here. While the definitions for the English defaults are loaded from the The localized definitions for all languages are loaded from the file languages.conf which is part of the locale specific sub-directory of the core package. The format of the definition file languages.conf is as follows:

 ...
 LANG_13_NAME=Albanian
 LANG_13_ISO639-2=alb/sqi
 LANG_13_ISO639-1=sq
 LANG_14_NAME=Aleut
 LANG_14_ISO639-2=ale
 LANG_15_NAME=Algonquian languages
 LANG_15_ISO639-2=alg
 ...
 

If you plan to add new translation files for language names make sure to set all the codes defined by the English language default file. It is sufficient to set a new file within an appropriate sub-directory of the core package, the class will find and automatically load it if the supported locale is requested by programs. For example if you plan to add a Dutch translation you have to add the file languages.conf to the sub-directory dut_NL or any valid Dutch locale directory.

There is a specific code range defined by ISO which can be used for local codes (e.g. program specific identifiers). To use this range simply create a subclass of LanguageCodes, execute super(); in order to have the initial caches properly installed, and then set your own local codes to the caches by calling the put method. For example a new mapping can be added with super.cacheNameBy639_2.put("qaa", "Local Slang 1");. Normally you will not set any ISO 639-1 codes but you could do so, as long as the official codes are not overwritten. If you implement a subclass the factory class cannot be used. Make sure to set also the translations currently in use in order to avoid unpredictable side effects.

Subclasses also have to take care of translations of language names in other languages than English (which is the default). If you set local codes as described above you must also set the corresponding translations in order to keep the class working. At the moment the class supports translations in French and German. You should also take care of the proper *.conf file encoding (UTF-8, ISO-8859-1 and so forth). At the moment all *.conf files used by the KAT framework are encoded with ISO-8859-1 since this is my default system encoding.

Since this class uses some amount of memory for the caches you could also create instances as usual if you only use this class once in your program. If you use the factory shared instance the memory will never be released during the JVM lifetime as long as you do not flush the factory. As you can see you can tune this class either for more performance or for a smaller memory footprint.

This class is tested in detail by the class TestLanguageCodes which you can find in the test directory of the KAT framework. Let me encourage you to always adapt and execute this test class when changes are applied since also little changes can cause errors.

The ISO 639-2 codes in the range from qaa...qtz are reserved for local use. They are part of the database but without any semantics.

Since:

1.5

Version:

$Revision: 1.12 $, $Date: 2016/01/01 15:43:01 $

Author:

Axel Schwolow

See Also:

I18NFactory, I18NUtils

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Hashtable<java.lang.String,java.lang.String>	cache639_1By639_2 Container for fast acquisition of ISO 639-1 codes by ISO 639-2 code.
protected java.util.Hashtable<java.lang.String,java.lang.String>	cache639_1ByName Container for fast acquisition of ISO 639-1 codes by language name.
protected java.util.Hashtable<java.lang.String,java.lang.String[]>	cache639_2By639_1 Container for fast acquisition of ISO 639-2 codes by ISO 639-1 code.
protected java.util.Hashtable<java.lang.String,java.lang.String[]>	cache639_2ByName Container for fast acquisition of ISO 639-2 codes by language name.
protected java.util.Hashtable<java.lang.String,java.lang.String[]>	cacheNameBy639_1 Container for fast acquisition of language names by ISO 639-1 code.
protected java.util.Hashtable<java.lang.String,java.lang.String[]>	cacheNameBy639_2 Container for fast acquisition of language names by ISO 639-2 code.
protected java.util.Hashtable<Locale,java.util.Hashtable<java.lang.String,java.lang.String[]>>	cacheTranslations Container for translations of the ISO language names (English is default).
protected Locale	locale Currently supported language for names as locale code, extracted from *.conf file.
protected java.lang.String	translations Target translation files pattern to append language code suffices.

Constructor Summary

Constructors

Constructor and Description
LanguageCodes() Constructor method.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	finalize() Cares for proper cleanup when is not needed any longer (helps gc).
java.lang.String	get639_1By639_2(java.lang.String code) Returns the ISO 639-1 code associated with a certain ISO 639-2 code.
java.lang.String	get639_1ByName(java.lang.String name, Locale locale) Returns the ISO 639-1 code associated with a certain language name.
java.lang.String[]	get639_2By639_1(java.lang.String code) Returns the ISO 639-2 code(s) associated with a certain ISO 639-1 code.
java.lang.String[]	get639_2ByName(java.lang.String name, Locale locale) Returns the ISO 639-2 code associated with a certain language name.
java.lang.String[]	get639_2Synonyms(java.lang.String code) Returns the ISO 639-2 synonyms if available (normally one single value).
java.util.Vector<java.lang.String>	getAll639_1() Returns the sorted list with supported ISO 639-1 codes.
java.util.Vector<java.lang.String>	getAll639_2(boolean synonyms) Returns the sorted list with supported ISO 639-2 codes.
java.util.Vector<java.lang.String>	getAllNames639_1(boolean synonyms, Locale locale) Returns the sorted list with supported language names associated with ISO 639-1 codes.
java.util.Vector<java.lang.String>	getAllNames639_2(boolean synonyms, Locale locale) Returns the sorted list with supported language names associated with ISO 639-2 codes.
Locale	getDefaultLocale() Returns the default locale used for language names (normally "eng_US" = English).
java.lang.String[]	getNamesBy639_1(java.lang.String code, Locale locale) Returns the language name(s) associated with a certain ISO 639-1 code.
java.lang.String[]	getNamesBy639_2(java.lang.String code, Locale locale) Returns the language name(s) associated with a certain ISO 639-2 code.
java.lang.String[]	getNameSynonyms(java.lang.String name, Locale locale) Returns the language name synonyms if available.
java.util.Vector<Locale>	getSupportedLocales(boolean synonyms) Returns the locales currently supported for the language names.
protected void	installInitialCaches() Installs the initial caches and loads ISO 639-1/639-2 data from *.conf file.
protected java.util.Hashtable	loadTranslation(Locale locale) Tries to load names translation data for a specific language code (ISO 639-1/2).

Methods inherited from class java.lang.Object

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

Field Detail

cacheNameBy639_1

protected java.util.Hashtable<java.lang.String,java.lang.String[]> cacheNameBy639_1

Container for fast acquisition of language names by ISO 639-1 code. Key is ISO 639-1 code (String), value is language names array (String[]).

cacheNameBy639_2

protected java.util.Hashtable<java.lang.String,java.lang.String[]> cacheNameBy639_2

Container for fast acquisition of language names by ISO 639-2 code. Key is ISO 639-2 code (String), value is language names array (String[]).

cache639_1ByName

protected java.util.Hashtable<java.lang.String,java.lang.String> cache639_1ByName

Container for fast acquisition of ISO 639-1 codes by language name. Key is language name (String), value is ISO 639-1 code (String).

cache639_1By639_2

protected java.util.Hashtable<java.lang.String,java.lang.String> cache639_1By639_2

Container for fast acquisition of ISO 639-1 codes by ISO 639-2 code. Key is ISO 639-2 code (String), value is ISO 639-1 code (String).

cache639_2ByName

protected java.util.Hashtable<java.lang.String,java.lang.String[]> cache639_2ByName

Container for fast acquisition of ISO 639-2 codes by language name. Key is language name (String), value is ISO 639-2 code array (String[]).

cache639_2By639_1

protected java.util.Hashtable<java.lang.String,java.lang.String[]> cache639_2By639_1

Container for fast acquisition of ISO 639-2 codes by ISO 639-1 code. Key is ISO 639-1 code (String), value is ISO 639-2 code array (String[]).

cacheTranslations

protected java.util.Hashtable<Locale,java.util.Hashtable<java.lang.String,java.lang.String[]>> cacheTranslations

Container for translations of the ISO language names (English is default). Key is locale code (String), value is translation container (Hashtable).

locale

protected Locale locale

Currently supported language for names as locale code, extracted from *.conf file.

translations

protected java.lang.String translations

Target translation files pattern to append language code suffices.

Constructor Detail

LanguageCodes

public LanguageCodes()

Constructor method.

Simply calls installInitialCaches which installs the initial caches and loads data from the *.conf file. See the method for details on how errors are propagated. As already said above you can implement your own subclasses with a constructor that reads the basic mapping data from a file other than the default *.conf file. To do this you have to call the installInitialCaches method with a different parameter. There is no need to call the superclass constructor first since this would cause unnecessary loading. If you implement a subclass the factory class cannot be used!

Since:

1.5

Method Detail

installInitialCaches

protected void installInitialCaches()

Installs the initial caches and loads ISO 639-1/639-2 data from *.conf file.

Currently there are three caches installed initially for some reason. The caches cacheNameBy639_1 and cacheNameBy639_2 are created to store the language names in the exact order (synonyms) and to remember the mappings between the code systems ISO 639-1 and ISO 639-2. The third cache cache639_2ByName is also initially created since the exact order of ISO 639-2 synonyms like "geo/kat" would be lost with only the two other caches. All the other caches are installed when needed in order to save resources.

Throws java.lang.RuntimeException if the resource file could not be read or if ISO 639-2 codes do not exist for a language or if there is no language set for the names. This all is absolutely necessary.

Since:

1.5

finalize

protected void finalize()
                 throws java.lang.Throwable

Cares for proper cleanup when is not needed any longer (helps gc).

The caches are cleared here to allow for a faster garbage collecting.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - Error indication

Since:

1.5

getNamesBy639_1

public java.lang.String[] getNamesBy639_1(java.lang.String code,
                                 Locale locale)

Returns the language name(s) associated with a certain ISO 639-1 code.

Throws NullPointerException if code is null. If a language name does not exist for the specified code or there is no appropriate names translation available then null is returned. Normally the returned array holds exactly one single language name, but for some languages one or more synonyms are defined.

If you like the names in a language other than the default (currently English) simply set the lang parameter appropriately (e.g. "de" for German language names). If you pass null here the names in the default language will be returned.

Parameters:

code - The ISO 639-1 code of interest, don't pass null values

locale - The locale code for the name(s) language, may be null

Returns:

The language name(s), null if code does not exist

Since:

1.5

loadTranslation

protected java.util.Hashtable loadTranslation(Locale locale)

Tries to load names translation data for a specific language code (ISO 639-1/2).

The result container is null if the given language code does not exist. The method also tries out all defined synonyms and associated codes (e.g. 639-2 for a given 639-1 code and vice versa). This way the method ensures that data is loaded even if the caller did not pass the exact language code.

Throws java.lang.RuntimeException if the resource file could not be imported properly.

Parameters:

locale - The locale code for which data shall be loaded

Returns:

The container with name translations, empty if translation file does not exist

Since:

1.5

getNamesBy639_2

public java.lang.String[] getNamesBy639_2(java.lang.String code,
                                 Locale locale)

Returns the language name(s) associated with a certain ISO 639-2 code.

Throws NullPointerException if code is null. If a language name does not exist for the specified code then null is returned. Normally the returned array holds exactly one single language name, but for some languages one or more synonyms are defined.

If you like the names in a language other than the default (currently English) simply set the lang parameter appropriately (e.g. "ger" for German language names). If you pass null here the names in the default language will be returned. Remember that the lang parameter must be a valid ISO 639-2 code.

Parameters:

code - The ISO 639-2 code of interest, don't pass null values

locale - The locale code for the name(s) language, may be null

Returns:

The language name(s), null if code does not exist

Since:

1.5

get639_1ByName

public java.lang.String get639_1ByName(java.lang.String name,
                              Locale locale)

Returns the ISO 639-1 code associated with a certain language name.

Throws NullPointerException if name is null. If an ISO 639-1 code does not exist for the specified language then null is returned.

If you use names in a language other than the default (currently English) simply set the lang parameter appropriately (e.g. "de" for German language names). If you pass null here the names in the default language will be returned. Make sure that the given name is defined for the specified language.

Parameters:

name - The language name of interest, don't pass null values

locale - The locale code for the name(s) language, may be null

Returns:

The ISO 639-1 code, null if language does not exist

Since:

1.5

get639_1By639_2

public java.lang.String get639_1By639_2(java.lang.String code)

Returns the ISO 639-1 code associated with a certain ISO 639-2 code.

Throws NullPointerException if code is null. If an ISO 639-1 code does not exist for the ISO 639-2 code then null is returned.

Parameters:

code - The ISO 639-2 code of interest, don't pass null values

Returns:

The ISO 639-1 code, null if ISO 639-2 code does not exist

Since:

1.5

get639_2ByName

public java.lang.String[] get639_2ByName(java.lang.String name,
                                Locale locale)

Returns the ISO 639-2 code associated with a certain language name.

Throws NullPointerException if name is null. If an ISO 639-2 code does not exist for the specified language then null is returned.

If you use names in a language other than the default (currently English) simply set the lang parameter appropriately (e.g. "de" for German language names). If you pass null here the names in the default language will be returned. Make sure that the given name is defined for the specified language.

Parameters:

name - The language name of interest, don't pass null values

locale - The locale code for the name(s) language, may be null

Returns:

The ISO 639-2 code(s), null if language does not exist

Since:

1.5

get639_2By639_1

public java.lang.String[] get639_2By639_1(java.lang.String code)

Returns the ISO 639-2 code(s) associated with a certain ISO 639-1 code.

Throws NullPointerException if code is null. If an ISO 639-2 code does not exist for the ISO 639-1 code then null is returned.

Parameters:

code - The ISO 639-1 code of interest, don't pass null values

Returns:

The ISO 639-2 code(s), null if ISO 639-1 code does not exist

Since:

1.5

getAllNames639_1

public java.util.Vector<java.lang.String> getAllNames639_1(boolean synonyms,
                                                  Locale locale)

Returns the sorted list with supported language names associated with ISO 639-1 codes.

Whenever there are multiple names defined for a certain language (synonyms) this method will return a composed name identifier like "Dutch; Flemish". The synonyms are separated by semicolon characters and can be easily parsed with StringTokenizer. If you do not like synonyms returned set the synonyms parameter to false. In this case the language names exactly consist of one single String which is the first defined language name (like "Dutch"). Be careful not to query the ISO codes for synonym-loaded language names like "Dutch; Flemish" since the getter methods only support querying one single name like "Dutch" or "Flemish"!

If you like the names in a language other than the default (currently English) simply set the lang parameter appropriately (e.g. "de" for German language names). If you pass null here the names in the default language will be returned. If an appropriate translation is not available the result container will be empty.

This method returns Vector containers with String objects ready to use with JComboBox instances.

Parameters:

synonyms - Shall synonyms be added separated by semicolon?

locale - The locale code for the name(s) language, may be null

Returns:

The sorted language names container with String objects

Since:

1.5

getAllNames639_2

public java.util.Vector<java.lang.String> getAllNames639_2(boolean synonyms,
                                                  Locale locale)

Returns the sorted list with supported language names associated with ISO 639-2 codes.

Whenever there are multiple names defined for a certain language (synonyms) this method will return a composed name identifier like "Dutch; Flemish". The synonyms are separated by semicolon characters and can be easily parsed with StringTokenizer. If you do not like synonyms returned set the synonyms parameter to false. In this case the language names exactly consist of one single String which is the first defined language name (like "Dutch"). Be careful not to query the ISO codes for synonym-loaded language names like "Dutch; Flemish" since the getter methods only support querying one single name like "Dutch" or "Flemish"!

If you like the names in a language other than the default (currently English) simply set the lang parameter appropriately (e.g. "de" for German language names). If you pass null here the names in the default language will be returned. If an appropriate translation is not available the result container will be empty.

This method returns Vector containers with String objects ready to use with JComboBox instances.

Parameters:

synonyms - Shall synonyms be added separated by semicolon?

locale - The locale code for the name(s) language, may be null

Returns:

The sorted language names container with String objects

Since:

1.5

getAll639_1

public java.util.Vector<java.lang.String> getAll639_1()

Returns the sorted list with supported ISO 639-1 codes.

This method returns Vector containers with String objects ready to use with JComboBox instances.

Returns:

The sorted ISO 639-1 codes container with String objects

Since:

1.5

getAll639_2

public java.util.Vector<java.lang.String> getAll639_2(boolean synonyms)

Returns the sorted list with supported ISO 639-2 codes.

Whenever there are multiple codes defined for a certain language (synonyms) this method will return a composed code identifier like "dut/nld". The synonyms are separated by slash characters and can be easily parsed with StringTokenizer. If you do not like synonyms returned set the synonyms parameter to false. In this case the ISO 639-2 codes exactly consist of one single String which is the first defined language code (like "dut"). Be careful not to query the names for synonym-loaded language codes like "dut/nld" since the getter methods only support querying one single code like "dut" or "nld"!

This method returns Vector containers with String objects ready to use with JComboBox instances.

Parameters:

synonyms - Shall synonyms be added separated by slashes?

Returns:

The sorted ISO 639-1 codes container with String objects

Since:

1.5

getDefaultLocale

public Locale getDefaultLocale()

Returns the default locale used for language names (normally "eng_US" = English).

Returns:

The current default locale, be prepared for null

Since:

1.5

getSupportedLocales

public java.util.Vector<Locale> getSupportedLocales(boolean synonyms)

Returns the locales currently supported for the language names.

Remember that is is absolutely necessary to use the exact locale to acquire the language specific language names. Currently there is no fallback mechanism implemented like returning "eng_US" when "eng" is requested. Only language synonyms defined by ISO 639-1/2 are possible. For instance you will get language names for "ger_DE" if you request "de_DE" or "deu_DE" since these are synonyms for one and same language German. You can specify whether to return only the concrete locale candidates in the path or the candidates plus the synonyms like "deu_DE" and "de_DE" for "ger_DE".

Parameters:

synonyms - Also add the ISO 639-1/2 synonyms like "deu_DE" for "ger_DE"?

Returns:

The supported locales, maybe empty

Since:

1.5

get639_2Synonyms

public java.lang.String[] get639_2Synonyms(java.lang.String code)

Returns the ISO 639-2 synonyms if available (normally one single value).

Throws NullPointerException if code is null. If synonyms are not defined for the specified code then null is returned.

Parameters:

code - The ISO 639-2 code to find synonyms for

Returns:

The ISO 639-2 synonyms, null if not available

Since:

1.5

getNameSynonyms

public java.lang.String[] getNameSynonyms(java.lang.String name,
                                 Locale locale)

Returns the language name synonyms if available.

Make sure that the lang parameter correctly reflects the language of the given first language name. Since there may be identical language names in different languages you might not get what you want in this case.

Throws NullPointerException if name is null. If synonyms are not defined for the specified name then null is returned.

Parameters:

name - The language name to find synonyms for

locale - The locale code for the name(s) language, may be null

Returns:

The language name synonyms, null if not available

Since:

1.5