Intl LocaleMatcher

import { match, LookupSupportedLocales, ResolveLocale } from "@formatjs/intl-localematcher";

const { match, LookupSupportedLocales, ResolveLocale } = require("@formatjs/intl-localematcher");

import { match } from "@formatjs/intl-localematcher";

// Basic locale matching with default 'best fit' algorithm
const bestLocale = match(
  ['fr-CA'], // requested locales
  ['en', 'fr', 'de'], // available locales
  'en' // default locale
);
// Result: 'fr' (best fit matches French)

// Complex locale matching with region variations
const regionMatch = match(
  ['zh-HK'],
  ['zh', 'zh-HANT', 'en'],
  'en'
);
// Result: 'zh-HANT' (Traditional Chinese matches Hong Kong)

/**
 * Match the best locale from available locales based on requested locales
 * @param requestedLocales - Array of requested locale strings
 * @param availableLocales - Array of available locale strings  
 * @param defaultLocale - Default fallback locale string
 * @param opts - Optional configuration object
 * @returns Best matching locale string
 */
function match(
  requestedLocales: readonly string[],
  availableLocales: readonly string[],
  defaultLocale: string,
  opts?: Opts
): string;

interface Opts {
  /** Locale matching algorithm: 'lookup' uses exact matching with fallbacks, 'best fit' uses intelligent language distance matching */
  algorithm: 'lookup' | 'best fit';
}

import { match } from "@formatjs/intl-localematcher";

// Default best fit matching
const result1 = match(['fr-XX', 'en'], ['fr', 'en'], 'en');
// Result: 'fr' (best fit finds French as closest match)

// No match found, returns default
const result2 = match([], ['zh-Hant-TW', 'en'], 'en');
// Result: 'en' (returns default when no locales requested)

// Complex locale with private extensions
const result3 = match(['fr-CA-x-foo'], ['zh-Hant-TW', 'fr', 'en'], 'en');
// Result: 'fr' (private extensions are ignored during matching)

/**
 * Find supported locales using lookup algorithm per ECMAScript spec
 * @param availableLocales - Array of available locale strings
 * @param requestedLocales - Array of requested locale strings
 * @returns Array of supported locale strings from available locales
 */
function LookupSupportedLocales(
  availableLocales: string[],
  requestedLocales: string[]
): string[];

import { LookupSupportedLocales } from "@formatjs/intl-localematcher";

// Find which locales are supported
const supported = LookupSupportedLocales(
  ['en', 'fr', 'de'], // available
  ['fr-CA', 'es', 'de-AT'] // requested
);
// Result: ['fr', 'de'] (fr matches fr-CA, de matches de-AT)

// No matches case
const noMatches = LookupSupportedLocales(['ja'], ['fr', 'es']);
// Result: [] (no supported locales found)

/**
 * Resolve locale with extension handling per ECMAScript spec
 * @param availableLocales - Set or array of available locales
 * @param requestedLocales - Array of requested locales
 * @param options - Options object with localeMatcher and other properties
 * @param relevantExtensionKeys - Array of relevant Unicode extension keys
 * @param localeData - Locale data record for extension processing
 * @param getDefaultLocale - Function returning default locale
 * @returns ResolveLocaleResult with resolved locale and extension data
 */
function ResolveLocale<K extends string, D extends {[k in K]: any}>(
  availableLocales: Set<string> | readonly string[],
  requestedLocales: readonly string[],
  options: {
    localeMatcher: string;
    [k: string]: string;
  },
  relevantExtensionKeys: K[],
  localeData: Record<string, D | undefined>,
  getDefaultLocale: () => string
): ResolveLocaleResult;

interface ResolveLocaleResult {
  /** The resolved locale string with Unicode extensions if applicable */
  locale: string;
  /** The base locale used for data lookup, without extensions */
  dataLocale: string;
  /** Additional properties populated from Unicode extension processing */
  [k: string]: any;
}

import { ResolveLocale } from "@formatjs/intl-localematcher";

// Basic resolution without extensions
const result = ResolveLocale(
  ['en', 'fr', 'de'],
  ['fr-CA'],
  { localeMatcher: 'best fit' },
  [], // no extension keys
  {}, // no locale data
  () => 'en'
);
// Result: { locale: 'fr', dataLocale: 'fr' }

// With extension processing
const extResult = ResolveLocale(
  ['en', 'fr'],
  ['fr-u-nu-latn'],
  { localeMatcher: 'lookup', nu: 'arab' },
  ['nu'], // numbering system extension
  { 'fr': { nu: ['latn', 'arab'] } }, // locale data
  () => 'en'
);
// Result: { locale: 'fr-u-nu-latn', dataLocale: 'fr', nu: 'latn' }

interface Opts {
  /** Locale matching algorithm */
  algorithm: 'lookup' | 'best fit';
}

interface LookupMatcherResult {
  /** The matched locale string */
  locale: string;
  /** Unicode extension string if present */
  extension?: string;
  /** Numbering system extension value if present */
  nu?: string;
}

interface Keyword {
  /** Unicode extension key */
  key: string;
  /** Unicode extension value */
  value: string;
}

interface ResolveLocaleResult {
  /** The resolved locale string with Unicode extensions if applicable */
  locale: string;
  /** The base locale used for data lookup, without extensions */
  dataLocale: string;
  /** Additional properties populated from Unicode extension processing */
  [k: string]: any;
}