Package com.ibm.icu.util

Class 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.

    • 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

      • 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.