Function findBestMatch

packages/intl-localematcher/abstract/utils.ts:341–496

(
  requestedLocales: readonly string[],
  supportedLocales: readonly string[],
  threshold: number = DEFAULT_MATCHING_THRESHOLD
)

const canonicalizedSupportedCache = new WeakMap<readonly string[], string[]>()

export function findBestMatch(
  requestedLocales: readonly string[],
  supportedLocales: readonly string[],
  threshold: number = DEFAULT_MATCHING_THRESHOLD
): LocaleMatchingResult {
  let lowestDistance = Infinity
  let result: LocaleMatchingResult = {
    matchedDesiredLocale: '',
    distances: {},
  }

  // Get or compute canonicalized supported locales (one by one to preserve indices)
  let canonicalizedSupportedLocales =
    canonicalizedSupportedCache.get(supportedLocales)
  if (!canonicalizedSupportedLocales) {
    canonicalizedSupportedLocales = supportedLocales.map(locale => {
      try {
        const canonical = Intl.getCanonicalLocales([locale])
        return canonical[0] || locale
      } catch {
        return locale
      }
    })
    canonicalizedSupportedCache.set(
      supportedLocales,
      canonicalizedSupportedLocales
    )
  }

  const supportedSet = new Set(canonicalizedSupportedLocales)

  // === TIER 1: FAST PATH - Exact Match ===
  // Check for exact matches in ALL requested locales
  // This is the fastest path and handles the majority of real-world cases
  for (let i = 0; i < requestedLocales.length; i++) {
    const desired = requestedLocales[i]
    if (supportedSet.has(desired)) {
      const distance = 0 + i * 40
      result.distances[desired] = {[desired]: distance}

      if (distance < lowestDistance) {
        lowestDistance = distance
        result.matchedDesiredLocale = desired
        result.matchedSupportedLocale = desired
      }

      // Only return immediately if this is the first requested locale (distance=0)
      // Otherwise, continue checking for potentially better matches
      if (i === 0) {
        return result
      }
    }
  }

  // If we found an exact match in Tier 1 (but not for first locale), check Tier 2
  // to see if there's a better fallback match with lower distance
  // If no exact match found, Tier 2 will find fallback matches