com.lf.commons.i18n

Class Locale

java.lang.Object

com.lf.commons.i18n.Locale

All Implemented Interfaces:

java.lang.Comparable<Locale>

public class Locale
extends java.lang.Object
implements java.lang.Comparable<Locale>

A Locale object represents a specific geographical, political, or cultural region.

Like the original java.util.Locale class this one adds some finer handling with languages, countries, and variants. The original class only supports the ISO 639-1 language codes (two letters), this class also adds support for ISO 639-2 language codes (three letters). This allows applications for finer localization. Especially if software authors want to publish a program translated in Lower German (code "nds") this would only be possible with the default locale "de_DE_nds" or some kind of construction abusing the variant part. Since most languages of the world have ISO 639-2 codes this standard seems the best choice. To be fair for most applications ISO 639-1 codes are OK. For this reason the country codes are supported as known from the java.util.Locale class (two uppercase letters). In most cases it should be possible to convert between this class and the default SUN implementation.

If you like to let your application support Lower German labels you can use "nds_DE" for the common case. If there are variants for example for different regions you can deploy the variant part like "nds_DE_Vechta", "nds_DE_Oldenburg", and so on. You can use whatever you want as variant, possibly you want to have a multipart variant like the locale id defined by the ISO 3166-2 for Germany "nds_DE_NI_Vechta", "nds_DE_NI_Oldenburg", "nds_DE_MV_Stralsund". Remember that the variant part is application specific, while the language and country codes supported by this class are standard values updated from time to time (or war to war).

To make programmer's life easier this class provides several methods to parse directory and file names in order to automatically detect available localizations for programs.

Since:

1.5

Version:

$Revision: 1.11 $, $Date: 2012/12/28 11:44:25 $

Author:

Axel Schwolow

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	country The country according to ISO 3166-1 (two letters).
protected static java.lang.String[]	iso3166_1 The countries array according to ISO 3166-1 (two letters).
protected static java.lang.String[]	iso639_1 The languages array according to ISO 639-1 (two letters).
protected static java.lang.String[]	iso639_2 The languages array according to ISO 639-2 (three letters) including synonyms.
protected static java.lang.String[][]	iso639_syns The two-dimensional array holding the synonym groups defined by ISO 639-1/2.
protected java.lang.String	language The language according to either ISO 639-1 (two letters) or ISO 639-2 (three letters).
protected java.lang.String	variant The application specific variant representing some fine grained regional specification.

Constructor Summary

Constructors

Constructor and Description
Locale() Constructor method for i18n purposes only.
Locale(java.lang.String language) Constructor method.
Locale(java.lang.String language, java.lang.String country) Constructor method.
Locale(java.lang.String language, java.lang.String country, java.lang.String variant) Constructor method.

Method Summary

Methods

Modifier and Type	Method and Description
int	compareTo(Locale other) Compares this object with the specified object for order.
boolean	equals(java.lang.Object obj) Returns true if this Locale is equal to another object.
java.lang.String	getCountry() Returns the country according to ISO 3166-1 (two letters).
static java.util.Locale	getJavaLocale(Locale locale) Provides a default Java for a Commons locale.
static java.lang.String	getJavaLocaleForDisplay(java.util.Locale locale, Locale userlocale) Provides a natural language string representation for a Java locale.
java.lang.String	getLanguage() Returns the language according to ISO 639-1 (two letters) or ISO 639-2 (three letters).
static java.lang.String	getLocaleForDisplay(Locale locale, Locale userlocale) Provides a natural language string representation for a locale.
static java.util.Vector<Locale>	getLocaleSynonyms(Locale locale) Returns a list of locales which are language synonyms defined by ISO 639-1/2.
java.lang.String	getVariant() Returns the application specific variant representing some fine grained regional specification.
int	hashCode() Computes hash code for containers like Hashtable.
static Locale	parseLocale(java.lang.String id) Returns the composed string representation with language, country, and variant.
java.lang.String	toString() Returns the composed string representation with language, country, and variant.
static java.lang.String	toString(java.lang.String language, java.lang.String country, java.lang.String variant) Returns the composed string representation with language, country, and variant.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

iso3166_1

protected static final java.lang.String[] iso3166_1

The countries array according to ISO 3166-1 (two letters). This array can be converted from CountryCodes data basis using the TestLocale.main() method.

iso639_1

protected static final java.lang.String[] iso639_1

The languages array according to ISO 639-1 (two letters). This array can be converted from LanguageCodes data basis using the TestLocale.main() method.

iso639_2

protected static final java.lang.String[] iso639_2

The languages array according to ISO 639-2 (three letters) including synonyms. This array can be converted from LanguageCodes data basis using the TestLocale.main() method.

iso639_syns

protected static final java.lang.String[][] iso639_syns

The two-dimensional array holding the synonym groups defined by ISO 639-1/2. This array can be converted from LanguageCodes data basis using the TestLocale.main() method.

language

protected java.lang.String language

The language according to either ISO 639-1 (two letters) or ISO 639-2 (three letters).

country

protected java.lang.String country

The country according to ISO 3166-1 (two letters).

variant

protected java.lang.String variant

The application specific variant representing some fine grained regional specification.

Constructor Detail

Locale

public Locale()
       throws java.lang.InstantiationException

Constructor method for i18n purposes only.

Can only be used if beans design time is set (e.g. by external tools like the I18NExtractor).

Throws:

java.lang.InstantiationException - Error indication

Since:

1.6

Locale

public Locale(java.lang.String language)

Constructor method.

Parameters:

language - The language according to either ISO 639-1 (two letters) or ISO 639-2 (three letters)

Throws:

java.lang.NullPointerException - Error indication

java.lang.IllegalArgumentException - Error indication

Since:

1.5

Locale

public Locale(java.lang.String language,
      java.lang.String country)

Constructor method.

Parameters:

language - The language according to either ISO 639-1 (two letters) or ISO 639-2 (three letters)

country - The country according to ISO 3166-1 (two letters)

Throws:

java.lang.NullPointerException - Error indication

java.lang.IllegalArgumentException - Error indication

Since:

1.5

Locale

public Locale(java.lang.String language,
      java.lang.String country,
      java.lang.String variant)

Constructor method.

Parameters:

language - The language according to either ISO 639-1 (two letters) or ISO 639-2 (three letters)

country - The country according to ISO 3166-1 (two letters)

variant - The application specific variant representing some fine grained regional specification

Throws:

java.lang.NullPointerException - Error indication

java.lang.IllegalArgumentException - Error indication

Since:

1.5

Method Detail

getLanguage

public java.lang.String getLanguage()

Returns the language according to ISO 639-1 (two letters) or ISO 639-2 (three letters).

Returns:

The current language

Since:

1.5

getCountry

public java.lang.String getCountry()

Returns the country according to ISO 3166-1 (two letters).

Returns:

The current country

Since:

1.5

getVariant

public java.lang.String getVariant()

Returns the application specific variant representing some fine grained regional specification.

Returns:

The current variant

Since:

1.5

equals

public boolean equals(java.lang.Object obj)

Returns true if this Locale is equal to another object.

Overrides:

equals in class java.lang.Object

Returns:

Are the objects equal?

Since:

1.5

toString

public java.lang.String toString()

Returns the composed string representation with language, country, and variant.

Like the java.util.Locale class the parts are separated with "_" characters. While the language and country codes are standardized the optional variant may have any lexical structure but should be of the form "[Text]_[Text]_...".

Overrides:

toString in class java.lang.Object

Returns:

The string representation

Since:

1.5

See Also:

parseLocale(String)

toString

public static java.lang.String toString(java.lang.String language,
                        java.lang.String country,
                        java.lang.String variant)

Returns the composed string representation with language, country, and variant.

Like the java.util.Locale class the parts are separated with "_" characters. While the language and country codes are standardized the optional variant may have any lexical structure but should be of the form "[Text]_[Text]_...".

Parameters:

language - The language

country - The country (optional)

variant - The variant (optional)

Returns:

The string representation

Since:

1.6

compareTo

public int compareTo(Locale other)

Compares this object with the specified object for order.

Specified by:

compareTo in interface java.lang.Comparable<Locale>

Parameters:

other - The locale to be compared

Returns:

A negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object

Since:

1.5

hashCode

public int hashCode()

Computes hash code for containers like Hashtable.

Overrides:

hashCode in class java.lang.Object

Returns:

Hash code

Since:

1.5

parseLocale

public static Locale parseLocale(java.lang.String id)

Returns the composed string representation with language, country, and variant.

Like the java.util.Locale class the parts are separated with "_" characters. While the language and country codes are standardized the optional variant may have any lexical structure but should be of the form "[Text]_[Text]_...".

For example the id "nds_DE_NI_Vechta_Süd" is parsed as language "nds", country "DE", variant "NI_Vechta_Süd".

Parameters:

id - The string to be parsed

Returns:

The object instance

Throws:

java.lang.NullPointerException - Error indication

java.lang.IllegalArgumentException - Error indication

Since:

1.5

See Also:

toString()

getLocaleSynonyms

public static java.util.Vector<Locale> getLocaleSynonyms(Locale locale)

Returns a list of locales which are language synonyms defined by ISO 639-1/2.

For instance the locale "ger_DE" has the synonyms "deu_DE" (ISO 639-2) and "de_DE" (ISO 639-1). This method works low-level and only makes use if the commons classes instead of high-level functionality which I18NUtils.getLocaleSynonyms(Locale) uses.

Parameters:

locale - The locale for thich to return the synonyms, may not be null

Returns:

The locale list, may be empty if no synonyms were found

Throws:

java.lang.NullPointerException - Error indication

Since:

1.5

See Also:

I18NUtils.getLocaleSynonyms(Locale)

getLocaleForDisplay

public static java.lang.String getLocaleForDisplay(Locale locale,
                                   Locale userlocale)

Provides a natural language string representation for a locale.

For instance the locale "ger_DE" could be displayed as "German (GERMANY)" for English users and as "Deutsch (DEUTSCHLAND)" for German speakers. The variant locales like "nds_DE_Vechta" will be displayed as "Niederdeutsch (DEUTSCHLAND, Vechta)" for German speakers. Simple locales like "en" will be displayed as "English" for English speakers.

Parameters:

locale - The locale to be displayed

userlocale - The display locale

Returns:

The localized representation

Throws:

java.lang.NullPointerException - Error indication

Since:

1.5

getJavaLocaleForDisplay

public static java.lang.String getJavaLocaleForDisplay(java.util.Locale locale,
                                       Locale userlocale)

Provides a natural language string representation for a Java locale.

For instance the locale "de_DE" could be displayed as "German (GERMANY)" for English users and as "Deutsch (DEUTSCHLAND)" for German speakers. Simple locales like "en" will be displayed as "English" for English speakers.

Parameters:

locale - The Java locale to be displayed

userlocale - The display locale

Returns:

The localized representation

Throws:

java.lang.NullPointerException - Error indication

Since:

1.6

getJavaLocale

public static java.util.Locale getJavaLocale(Locale locale)

Provides a default Java for a Commons locale.

For instance a "eng_US" locale is converted to "en_US" here.

Parameters:

locale - The locale to be converted

Returns:

The Java locale, null if not available

Throws:

java.lang.NullPointerException - Error indication

Since:

1.6