com.ibm.icu.util

Class LocaleMatcher

java.lang.Object

com.ibm.icu.util.LocaleMatcher

public class LocaleMatcher
extends Object

Provides a way to match the languages (locales) supported by a product to the languages (locales) acceptable to a user, and get the best match. For example:

 LocaleMatcher matcher = new LocaleMatcher("fr, en-GB, en");
 
 // afterwards:
 matcher.getBestMatch("en-US").toLanguageTag() => "en"
 

It takes into account when languages are close to one another, such as fil and tl, and when language regional variants are close, like en-GB and en-AU. It also handles scripts, like zh-Hant vs zh-TW. For examples, see the test file.

All classes implementing this interface should be immutable. Often a product will just need one static instance, built with the languages that it supports. However, it may want multiple instances with different default languages based on additional information, such as the domain.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LocaleMatcher.LanguageMatcherData Deprecated. This API is ICU internal only.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEBUG Deprecated. This API is ICU internal only.

Constructor Summary

Constructors

Constructor and Description
LocaleMatcher(LocalePriorityList languagePriorityList) Create a new language matcher.
LocaleMatcher(LocalePriorityList languagePriorityList, LocaleMatcher.LanguageMatcherData matcherData) Deprecated. This API is ICU internal only.
LocaleMatcher(LocalePriorityList languagePriorityList, LocaleMatcher.LanguageMatcherData matcherData, double threshold) Deprecated. This API is ICU internal only.
LocaleMatcher(String languagePriorityListString) Create a new language matcher from a String form.

Method Summary

Modifier and Type	Method and Description
ULocale	canonicalize(ULocale ulocale) Canonicalize a locale (language).
ULocale	getBestMatch(LocalePriorityList languageList) Get the best match for a LanguagePriorityList
ULocale	getBestMatch(String languageList) Convenience method: Get the best match for a LanguagePriorityList
ULocale	getBestMatch(ULocale... ulocales) Deprecated. This API is ICU internal only.
ULocale	getBestMatch(ULocale ulocale) Get the best match for an individual language code.
static ICUResourceBundle	getICUSupplementalData() Deprecated. This API is ICU internal only.
static double	match(ULocale a, ULocale b) Deprecated. This API is ICU internal only.
double	match(ULocale desired, ULocale desiredMax, ULocale supported, ULocale supportedMax) Returns a fraction between 0 and 1, where 1 means that the languages are a perfect match, and 0 means that they are completely different.
String	toString() Returns a string containing a concise, human-readable description of this object.

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG

@Deprecated
public static final boolean DEBUG

Deprecated. This API is ICU internal only.

See Also:

Constant Field Values

Constructor Detail

LocaleMatcher

public LocaleMatcher(LocalePriorityList languagePriorityList)

Create a new language matcher. The highest-weighted language is the default. That means that if no other language is matches closer than a given threshold, that default language is chosen. Typically the default is English, but it could be different based on additional information, such as the domain of the page.

Parameters:

languagePriorityList - weighted list

LocaleMatcher

public LocaleMatcher(String languagePriorityListString)

Create a new language matcher from a String form. The highest-weighted language is the default.

Parameters:

languagePriorityListString - String form of LanguagePriorityList

LocaleMatcher

@Deprecated
public LocaleMatcher(LocalePriorityList languagePriorityList,
                                 LocaleMatcher.LanguageMatcherData matcherData)

Deprecated. This API is ICU internal only.

Internal testing function; may expose API later.

Parameters:

languagePriorityList - LocalePriorityList to match

matcherData - Internal matching data

LocaleMatcher

@Deprecated
public LocaleMatcher(LocalePriorityList languagePriorityList,
                                 LocaleMatcher.LanguageMatcherData matcherData,
                                 double threshold)

Deprecated. This API is ICU internal only.

Internal testing function; may expose API later.

Parameters:

languagePriorityList - LocalePriorityList to match

matcherData - Internal matching data

Method Detail

match

public double match(ULocale desired,
                    ULocale desiredMax,
                    ULocale supported,
                    ULocale supportedMax)

Returns a fraction between 0 and 1, where 1 means that the languages are a perfect match, and 0 means that they are completely different. Note that the precise values may change over time; no code should be made dependent on the values remaining constant.

Parameters:

desired - Desired locale

desiredMax - Maximized locale (using likely subtags)

supported - Supported locale

supportedMax - Maximized locale (using likely subtags)

Returns:

value between 0 and 1, inclusive.

canonicalize

public ULocale canonicalize(ULocale ulocale)

Canonicalize a locale (language). Note that for now, it is canonicalizing according to CLDR conventions (he vs iw, etc), since that is what is needed for likelySubtags.

Parameters:

ulocale - language/locale code

Returns:

ULocale with remapped subtags.

getBestMatch

public ULocale getBestMatch(LocalePriorityList languageList)

Get the best match for a LanguagePriorityList

Parameters:

languageList - list to match

Returns:

best matching language code

getBestMatch

public ULocale getBestMatch(String languageList)

Convenience method: Get the best match for a LanguagePriorityList

Parameters:

languageList - String form of language priority list

Returns:

best matching language code

getBestMatch

public ULocale getBestMatch(ULocale ulocale)

Get the best match for an individual language code.

Parameters:

ulocale - locale/language code to match

Returns:

best matching language code

getBestMatch

@Deprecated
public ULocale getBestMatch(ULocale... ulocales)

Deprecated. This API is ICU internal only.

toString

public String toString()

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Overrides:

toString in class Object

Returns:

a printable representation of this object.

getICUSupplementalData

@Deprecated
public static ICUResourceBundle getICUSupplementalData()

Deprecated. This API is ICU internal only.

match

@Deprecated
public static double match(ULocale a,
                                       ULocale b)

Deprecated. This API is ICU internal only.