Locale Information Enricher

A utility that enriches incomplete locale identifiers by expanding them into their full canonical forms with language, script, and region information based on cultural and linguistic defaults.

Requirements

Implement a locale enrichment system that takes partial locale identifiers (such as language-only codes or language-region pairs without scripts) and expands them into complete locale identifiers with full language-script-region information.

Input Processing

The system should accept:

• Single language codes (e.g., en, zh, ja)
• Language-region combinations (e.g., zh-TW, zh-CN, sr-RS)
• Language-script combinations (e.g., zh-Hant, ar-Arab)
• Already complete locale identifiers (e.g., en-Latn-US)

Output Format

For each input locale, the system should produce:

• The fully expanded locale identifier with all three components (language, script, region)
• The output should follow BCP 47 locale identifier format

Behavior Requirements

• The enrichment should follow cultural and linguistic defaults (e.g., Chinese defaults to Simplified script with China region, Japanese defaults to Japan)
• Language-region combinations should infer the appropriate script based on the region
• Already complete locale identifiers should be returned as-is or normalized
• Invalid or unsupported locale identifiers should be handled gracefully

Test Cases

Basic Language Expansion

• Given the language code en, the enricher expands it to en-Latn-US @test
• Given the language code ja, the enricher expands it to ja-Jpan-JP @test
• Given the language code ar, the enricher expands it to ar-Arab-EG @test

Language-Region Expansion

• Given zh-CN, the enricher expands it to zh-Hans-CN (Simplified Chinese) @test
• Given zh-TW, the enricher expands it to zh-Hant-TW (Traditional Chinese) @test
• Given sr-RS, the enricher expands it to sr-Cyrl-RS (Serbian with Cyrillic script) @test

Multiple Locale Processing

• Given an array of locale codes ['en', 'zh', 'fr', 'ja'], the enricher processes all locales and returns an array of expanded forms @test

Implementation

@generates

API

/**
 * Enriches a single locale identifier by expanding it to include
 * language, script, and region components.
 *
 * @param locale - A BCP 47 locale identifier (e.g., 'en', 'zh-TW', 'ja-Jpan-JP')
 * @returns The expanded locale identifier with all components
 */
export function enrichLocale(locale: string): string;

/**
 * Enriches multiple locale identifiers.
 *
 * @param locales - An array of BCP 47 locale identifiers
 * @returns An array of expanded locale identifiers
 */
export function enrichLocales(locales: string[]): string[];

Dependencies { .dependencies }

@formatjs/intl-localematcher { .dependency }

Provides locale matching and manipulation capabilities including locale maximization based on CLDR data.