Locale Preferences Parser

Build a utility that parses and applies user locale preferences from locale strings with Unicode extensions to formatting configuration objects.

Requirements

Your utility should:

1. Accept a locale string that may include Unicode extensions (e.g., en-US-u-ca-buddhist-nu-thai-hc-h12)
2. Extract the Unicode extension values for calendar system, numbering system, and hour cycle
3. Merge these extracted values with user-provided options, where user options take precedence
4. Return a configuration object containing the resolved locale and the applied settings

The utility should handle:

• Locale strings with no Unicode extensions (e.g., en-US)
• Locale strings with partial Unicode extensions (e.g., en-US-u-ca-gregory)
• User options that override Unicode extension values
• Multiple Unicode extension keys in any order

Configuration Object Format

The returned configuration should have this structure:

{
  locale: string,           // The original locale identifier
  calendar: string | null,  // Resolved calendar system (e.g., 'buddhist', 'gregory')
  numberingSystem: string | null,  // Resolved numbering system (e.g., 'thai', 'latn')
  hourCycle: string | null  // Resolved hour cycle (e.g., 'h12', 'h23')
}

Test Cases

• Parsing a locale with all three Unicode extensions returns correct values for calendar, numbering system, and hour cycle @test
• Parsing a locale with only calendar extension returns the calendar value and null for others @test
• Parsing a locale without Unicode extensions returns null for all extension values @test
• User options override Unicode extension values when both are present @test

Implementation

@generates

API

export interface LocaleConfig {
  locale: string;
  calendar: string | null;
  numberingSystem: string | null;
  hourCycle: string | null;
}

export interface UserOptions {
  calendar?: string;
  numberingSystem?: string;
  hourCycle?: string;
}

/**
 * Parse a locale string with Unicode extensions and merge with user options
 *
 * @param localeString - A BCP 47 locale identifier that may include Unicode extensions
 * @param options - Optional user preferences that override extension values
 * @returns Configuration object with resolved locale and extension values
 */
export function parseLocalePreferences(
  localeString: string,
  options?: UserOptions
): LocaleConfig;

Dependencies { .dependencies }

@formatjs/intl-localematcher { .dependency }

Provides Unicode locale extension parsing and processing capabilities.