Class 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:
     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
    • 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​(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
      • 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​(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
      • 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • 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 user
        supported - 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​(java.util.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.