Package 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.
- Author:
- markdavis@google.com
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
LocaleMatcher.LanguageMatcherData
Deprecated.This API is ICU internal only.
-
Field Summary
Fields Modifier and Type Field Description static boolean
DEBUG
Deprecated.This API is ICU internal only.
-
Constructor Summary
Constructors Constructor 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
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description ULocale
canonicalize(ULocale ulocale)
Canonicalize a locale (language).int
distance(ULocale desired, ULocale supported)
Deprecated.ICU 59: This API is a technical preview.ULocale
getBestMatch(LocalePriorityList languageList)
Get the best match for a LanguagePriorityListULocale
getBestMatch(ULocale ulocale)
Get the best match for an individual language code.ULocale
getBestMatch(ULocale... ulocales)
Deprecated.This API is ICU internal only.ULocale
getBestMatch(String languageList)
Convenience method: Get the best match for a LanguagePriorityListULocale
getBestMatch(LinkedHashSet<ULocale> desiredLanguages, Output<ULocale> outputBestDesired)
Deprecated.ICU 59: This API is a technical preview.static com.ibm.icu.impl.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.LocaleMatcher
setDefaultLanguage(ULocale defaultLanguage)
Deprecated.ICU 59: This API is a technical preview.LocaleMatcher
setFavorScript(boolean favorScript)
Deprecated.ICU 59: This API is a technical preview.String
toString()
-
-
-
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 matchmatcherData
- 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 matchmatcherData
- 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 localedesiredMax
- Maximized locale (using likely subtags)supported
- Supported localesupportedMax
- 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.
-
getICUSupplementalData
@Deprecated public static com.ibm.icu.impl.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.
-
distance
@Deprecated public int distance(ULocale desired, ULocale supported)
Deprecated.ICU 59: This API is a technical preview. It may change in an upcoming release.Returns the distance between the two languages, using the new CLDR syntax (see getBestMatch). The values are not necessarily symmetric.- Parameters:
desired
- A locale desired by the usersupported
- A locale supported by a program.- Returns:
- A return of 0 is a complete match, and 100 is a complete mismatch (above the thresholdDistance). A language is first maximized with add likely subtags, then compared.
-
getBestMatch
@Deprecated public ULocale getBestMatch(LinkedHashSet<ULocale> desiredLanguages, Output<ULocale> outputBestDesired)
Deprecated.ICU 59: This API is a technical preview. It may change in an upcoming release.Get the best match between the desired languages and supported languages This supports the new CLDR syntax to provide for better matches within regional clusters (such as maghreb Arabic vs non-maghreb Arabic, or regions that use en-GB vs en-US) and also matching between regions and macroregions, such as comparing es-419 to es-AR).- Parameters:
desiredLanguages
- Typically the supplied user's languages, in order of preference, with best first.outputBestDesired
- The one of the desired languages that matched best. Set to null if the best match was not below the threshold distance.- Returns:
- best-match supported language
-
setDefaultLanguage
@Deprecated public LocaleMatcher setDefaultLanguage(ULocale defaultLanguage)
Deprecated.ICU 59: This API is a technical preview. It may change in an upcoming release.Set the default language, with null = default = first supported language- Parameters:
defaultLanguage
- Language to use in case the threshold for distance is exceeded.- Returns:
- this, for chaining
-
setFavorScript
@Deprecated public LocaleMatcher setFavorScript(boolean favorScript)
Deprecated.ICU 59: This API is a technical preview. It may change in an upcoming release.If true, then the language differences are smaller than than script differences. This is used in situations (such as maps) where it is better to fall back to the same script than a similar language.- Parameters:
favorScript
- Set to true to treat script as most important.- Returns:
- this, for chaining.
-
-