com.ibm.icu.util
Class LocaleMatcher

java.lang.Object
  extended by com.ibm.icu.util.LocaleMatcher

public class LocaleMatcher
extends java.lang.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:

 LanguageMatcher matcher = new StandardLanguageMatcher("fr, en-GB, en");
 
 // afterwards:
 matcher.getBestMatch(LanguageCode.US).first == LanguageCode.ENGLISH
 
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
Status:
Draft ICU 4.4.

Nested Class Summary
static class LocaleMatcher.LanguageMatcherData
          Deprecated. This API is ICU internal only.
 
Constructor Summary
LocaleMatcher(LocalePriorityList languagePriorityList)
          Create a new language matcher.
LocaleMatcher(LocalePriorityList languagePriorityList, LocaleMatcher.LanguageMatcherData matcherData)
          Deprecated. This API is ICU internal only.
LocaleMatcher(java.lang.String languagePriorityListString)
          Create a new language matcher from a String form.
 
Method Summary
 ULocale canonicalize(ULocale ulocale)
          Canonicalize a locale (language).
 ULocale getBestMatch(LocalePriorityList languageList)
          Get the best match for a LanguagePriorityList
 ULocale getBestMatch(java.lang.String languageList)
          Convenience method: Get the best match for a LanguagePriorityList
 ULocale getBestMatch(ULocale ulocale)
          Get the best match for an individual language code.
 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.
 java.lang.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 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
Status:
Draft ICU 4.4.

LocaleMatcher

public LocaleMatcher(java.lang.String languagePriorityListString)
Create a new language matcher from a String form. The highest-weighted language is the default.

Parameters:
languagePriorityListString - String form of LanguagePriorityList
Status:
Draft ICU 4.4.

LocaleMatcher

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
Status:
Internal. This API is ICU internal only.
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.
Status:
Draft ICU 4.4.

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.
Status:
Draft ICU 4.4.

getBestMatch

public ULocale getBestMatch(LocalePriorityList languageList)
Get the best match for a LanguagePriorityList

Parameters:
languageList - list to match
Returns:
best matching language code
Status:
Draft ICU 4.4.

getBestMatch

public ULocale getBestMatch(java.lang.String languageList)
Convenience method: Get the best match for a LanguagePriorityList

Parameters:
languageList - String form of language priority list
Returns:
best matching language code
Status:
Draft ICU 4.4.

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
Status:
Draft ICU 4.4.

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object
Status:
Draft ICU 4.4.


Copyright (c) 2011 IBM Corporation and others.