com.ibm.icu.util

Class LocaleMatcher

java.lang.Object

com.ibm.icu.util.LocaleMatcher

public final class LocaleMatcher
extends Object

Immutable class that picks the best match between a user's desired locales and an application's supported locales.

Example:

 LocaleMatcher matcher = LocaleMatcher.builder().setSupportedLocales("fr, en-GB, en").build();
 Locale bestSupported = matcher.getBestLocale(Locale.US);  // "en"
 

A matcher takes into account when languages are close to one another, such as Danish and Norwegian, and when regional variants are close, like en-GB and en-AU as opposed to en-US.

If there are multiple supported locales with the same (language, script, region) likely subtags, then the current implementation returns the first of those locales. It ignores variant subtags (except for pseudolocale variants) and extensions. This may change in future versions.

For example, the current implementation does not distinguish between de, de-DE, de-Latn, de-1901, de-u-co-phonebk.

If you prefer one equivalent locale over another, then provide only the preferred one, or place it earlier in the list of supported locales.

Otherwise, the order of supported locales may have no effect on the best-match results. The current implementation compares each desired locale with supported locales in the following order: 1. Default locale, if supported; 2. CLDR "paradigm locales" like en-GB and es-419; 3. other supported locales. This may change in future versions.

Often a product will just need one matcher 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.

This class is not intended for public subclassing.

Author:

markdavis@google.com

Status:

Stable ICU 4.4.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LocaleMatcher.Builder LocaleMatcher Builder.
static class	LocaleMatcher.Demotion Builder option for whether all desired locales are treated equally or earlier ones are preferred.
static class	LocaleMatcher.Direction Builder option for whether to include or ignore one-way (fallback) match data.
static class	LocaleMatcher.FavorSubtag Builder option for whether the language subtag or the script subtag is most important.
static class	LocaleMatcher.Result Data for the best-matching pair of a desired and a supported locale.

Constructor Summary

Constructors

Constructor and Description
LocaleMatcher(LocalePriorityList supportedLocales) Copies the supported locales, preserving iteration order, and constructs a LocaleMatcher.
LocaleMatcher(String supportedLocales) Parses the string like LocalePriorityList does and constructs a LocaleMatcher for the supported locales parsed from the string.

Method Summary

Modifier and Type	Method and Description
static LocaleMatcher.Builder	builder() Returns a builder used in chaining parameters for building a LocaleMatcher.
ULocale	canonicalize(ULocale locale) Partially canonicalizes a locale (language).
Locale	getBestLocale(Iterable<Locale> desiredLocales) Returns the supported locale which best matches one of the desired locales.
Locale	getBestLocale(Locale desiredLocale) Returns the supported locale which best matches the desired locale.
LocaleMatcher.Result	getBestLocaleResult(Iterable<Locale> desiredLocales) Returns the best match between the desired and supported locales.
LocaleMatcher.Result	getBestLocaleResult(Locale desiredLocale) Returns the best match between the desired locale and the supported locales.
ULocale	getBestMatch(Iterable<ULocale> desiredLocales) Returns the supported locale which best matches one of the desired locales.
ULocale	getBestMatch(String desiredLocaleList) Parses the string like LocalePriorityList does and returns the supported locale which best matches one of the desired locales.
ULocale	getBestMatch(ULocale desiredLocale) Returns the supported locale which best matches the desired locale.
LocaleMatcher.Result	getBestMatchResult(Iterable<ULocale> desiredLocales) Returns the best match between the desired and supported locales.
LocaleMatcher.Result	getBestMatchResult(ULocale desiredLocale) Returns the best match between the desired locale and the supported locales.
boolean	isMatch(Locale desired, Locale supported) Returns true if the pair of locales matches acceptably.
boolean	isMatch(ULocale desired, ULocale supported) Returns true if the pair of locales matches acceptably.
double	match(ULocale desired, ULocale desiredMax, ULocale supported, ULocale supportedMax) Deprecated. ICU 65 Build and use a matcher rather than comparing pairs of locales.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

LocaleMatcher

public LocaleMatcher(LocalePriorityList supportedLocales)

Copies the supported locales, preserving iteration order, and constructs a LocaleMatcher. The first locale is used as the default locale for when there is no good match.

Parameters:

supportedLocales - list of locales

Status:

Stable ICU 4.4.

LocaleMatcher

public LocaleMatcher(String supportedLocales)

Parses the string like LocalePriorityList does and constructs a LocaleMatcher for the supported locales parsed from the string. The first one (in LocalePriorityList iteration order) is used as the default locale for when there is no good match.

Parameters:

supportedLocales - the string of locales to set, to be parsed like LocalePriorityList does

Status:

Stable ICU 4.4.

Method Detail

builder

public static LocaleMatcher.Builder builder()

Returns a builder used in chaining parameters for building a LocaleMatcher.

Returns:

a new Builder object

Status:

Stable ICU 65.

getBestMatch

public ULocale getBestMatch(ULocale desiredLocale)

Returns the supported locale which best matches the desired locale.

Parameters:

desiredLocale - Typically a user's language.

Returns:

the best-matching supported locale.

Status:

Stable ICU 4.4.

getBestMatch

public ULocale getBestMatch(Iterable<ULocale> desiredLocales)

Returns the supported locale which best matches one of the desired locales.

Parameters:

desiredLocales - Typically a user's languages, in order of preference (descending). (In ICU 4.4..63 this parameter had type LocalePriorityList.)

Returns:

the best-matching supported locale.

Status:

Stable ICU 4.4.

getBestMatch

public ULocale getBestMatch(String desiredLocaleList)

Parses the string like LocalePriorityList does and returns the supported locale which best matches one of the desired locales.

Parameters:

desiredLocaleList - Typically a user's languages, as a string which is to be parsed like LocalePriorityList does.

Returns:

the best-matching supported locale.

Status:

Stable ICU 4.4.

getBestLocale

public Locale getBestLocale(Locale desiredLocale)

Returns the supported locale which best matches the desired locale.

Parameters:

desiredLocale - Typically a user's language.

Returns:

the best-matching supported locale.

Status:

Stable ICU 65.

getBestLocale

public Locale getBestLocale(Iterable<Locale> desiredLocales)

Returns the supported locale which best matches one of the desired locales.

Parameters:

desiredLocales - Typically a user's languages, in order of preference (descending).

Returns:

the best-matching supported locale.

Status:

Stable ICU 65.

getBestMatchResult

public LocaleMatcher.Result getBestMatchResult(ULocale desiredLocale)

Returns the best match between the desired locale and the supported locales.

Parameters:

desiredLocale - Typically a user's language.

Returns:

the best-matching pair of the desired and a supported locale.

Status:

Stable ICU 65.

getBestMatchResult

public LocaleMatcher.Result getBestMatchResult(Iterable<ULocale> desiredLocales)

Returns the best match between the desired and supported locales.

Parameters:

desiredLocales - Typically a user's languages, in order of preference (descending).

Returns:

the best-matching pair of a desired and a supported locale.

Status:

Stable ICU 65.

getBestLocaleResult

public LocaleMatcher.Result getBestLocaleResult(Locale desiredLocale)

Returns the best match between the desired locale and the supported locales.

Parameters:

desiredLocale - Typically a user's language.

Returns:

the best-matching pair of the desired and a supported locale.

Status:

Stable ICU 65.

getBestLocaleResult

public LocaleMatcher.Result getBestLocaleResult(Iterable<Locale> desiredLocales)

Returns the best match between the desired and supported locales.

Parameters:

desiredLocales - Typically a user's languages, in order of preference (descending).

Returns:

the best-matching pair of a desired and a supported locale.

Status:

Stable ICU 65.

isMatch

public boolean isMatch(Locale desired,
                       Locale supported)

Returns true if the pair of locales matches acceptably. This is influenced by Builder options such as setDirection(), setFavorSubtag(), and setMaxDistance().

Parameters:

desired - The desired locale.

supported - The supported locale.

Returns:

true if the pair of locales matches acceptably.

Status:

Stable ICU 68.

isMatch

public boolean isMatch(ULocale desired,
                       ULocale supported)

Returns true if the pair of locales matches acceptably. This is influenced by Builder options such as setDirection(), setFavorSubtag(), and setMaxDistance().

Parameters:

desired - The desired locale.

supported - The supported locale.

Returns:

true if the pair of locales matches acceptably.

Status:

Stable ICU 68.

match

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

Deprecated. ICU 65 Build and use a matcher rather than comparing pairs of locales.

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.

This is mostly an implementation detail, and the precise values may change over time. The implementation may use either the maximized forms or the others ones, or both. The implementation may or may not rely on the forms to be consistent with each other.

Callers should construct and use a matcher rather than match pairs of locales directly.

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 locale)

Partially canonicalizes 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.

Currently, this is a much simpler canonicalization than what the ULocale class does: The language/script/region subtags are each mapped separately, ignoring the other subtags. If none of these change, then the input locale is returned. Otherwise a new ULocale with only those subtags is returned, removing variants and extensions.

Parameters:

locale - language/locale code

Returns:

ULocale with remapped subtags.

Status:

Stable ICU 4.4.

toString

public String toString()

Overrides:

toString in class Object

Status:

Stable ICU 4.4.