Interface LocaleMatcher

All Known Subinterfaces:
Strings
public interface LocaleMatcher
Contract for matching an input Locale or List<Locale.LanguageRange> to an appropriate localized strings Locale.

Lokalized's implementation prefers exact and CLDR-canonical matches, then CLDR parent-locale fallback, then script-aware likely-subtag matches. If multiple supported localized strings files still share the same language, configured tiebreakers determine which locale wins. Unmatched, root, and undetermined requests resolve to the configured fallback locale when using bestMatchFor(...). The strict matchFor(...) methods represent the same state as an unmatched LocaleMatchResult instead of manufacturing a match.

Non-bare wildcard language ranges use RFC 4647 extended filtering only; they are not broadened through CLDR, likely-subtag, or primary-language heuristics, and successful results report LocaleMatchType.EXTENDED_RANGE. When multiple ranges match one supported locale, the most-specific exact, canonical, or structural range determines its effective quality, including a q=0 exclusion.

Author:
Mark Allen

  • Field Details

  • Method Details

    • matchFor

      default @NonNull LocaleMatchResult matchFor(@NonNull Locale locale)
      Strictly negotiates a locale without manufacturing a configured-fallback match.
      Parameters:
      locale - requested locale, not null
      Returns:
      diagnostic match result, not null
      Throws:
      IllegalArgumentException - if the locale is not well-formed
      Since:
      3.0.0

    • matchFor

      @NonNull LocaleMatchResult matchFor(@NonNull List<@NonNull Locale.LanguageRange> languageRanges)
      Strictly negotiates language ranges without manufacturing a configured-fallback match.
      Parameters:
      languageRanges - requested language ranges, not null
      Returns:
      diagnostic match result, not null
      Throws:
      IllegalArgumentException - if more than MAXIMUM_LANGUAGE_RANGES language ranges are supplied
      Since:
      3.0.0

    • bestMatchFor

      @NonNull Locale bestMatchFor(@NonNull Locale locale)
      Given a locale, determine the best-matching localized strings file's locale.
      Parameters:
      locale - the locale for which to find the best match.
      Returns:
      the best-matching locale, not null
      Throws:
      IllegalArgumentException - if the locale is not well-formed

    • bestMatchFor

      @NonNull Locale bestMatchFor(@NonNull List<@NonNull Locale.LanguageRange> languageRanges)
      Given a list of language ranges (e.g. as parsed from an Accept-Language HTTP request header), determine the best-matching localized strings file's locale.
      Parameters:
      languageRanges - the ordered list of language ranges for which to find the best match.
      Returns:
      the best-matching locale, not null
      Throws:
      IllegalArgumentException - if more than MAXIMUM_LANGUAGE_RANGES language ranges are supplied

    • bestMatchForAcceptLanguage

      default @NonNull Locale bestMatchForAcceptLanguage(@Nullable String acceptLanguage)
      Given a raw Accept-Language HTTP field value, determines the best-matching localized strings file's locale.

      This is a fail-soft convenience for request handling. A missing, blank, malformed, or longer than 4,096 UTF-16 code-unit value returns the configured fallback locale. The length limit is applied before parsing so parser work is bounded independently of the parsed-range limit. HTTP optional whitespace and empty list elements are normalized before parsing. The configured fallback is also returned if parsing produces more than MAXIMUM_LANGUAGE_RANGES ranges, which can happen when Locale.LanguageRange.parse(String) adds IANA-equivalent ranges. A valid parsed list is passed through whole; preferences are never truncated. Use matchFor(List) or bestMatchFor(List) when language ranges have already been parsed and strict limit enforcement is desired.

      Parameters:
      acceptLanguage - raw, already-combined Accept-Language field value, or null if absent
      Returns:
      the best-matching locale, or the configured fallback for unusable input, not null
      Since:
      3.0.0