Regional Content Delivery Service

A global web application needs to deliver region-appropriate content to users. The service receives user locale preferences and must match them against available regional content variations, using intelligent region-aware matching to provide the best user experience.

Requirements

Build a content localization service that:

1. Accepts an array of user-preferred locales (in order of preference)
2. Matches them against available content locales using region-aware matching
3. Returns the best matching locale for content delivery
4. Uses intelligent matching that understands regional relationships (e.g., Chinese variants for different regions, English variants across territories)
5. Falls back to a sensible default when no good match is found

The service should handle various scenarios:

• Users from Hong Kong requesting Chinese content should receive Traditional Chinese
• Users requesting regional English variants (en-GB, en-CA) should match appropriately
• Users from specific regions should match broader regional content when exact matches aren't available
• The matching should consider linguistic and regional proximity

Test Cases

• When a user prefers ['zh-HK'] and available locales are ['zh-Hans', 'zh-Hant', 'en'], the service returns 'zh-Hant' because Hong Kong uses Traditional Chinese @test

• When a user prefers ['zh-CN'] and available locales are ['zh-Hans', 'zh-Hant', 'en'], the service returns 'zh-Hans' because Mainland China uses Simplified Chinese @test

• When a user prefers ['en-GB'] and available locales are ['en-US', 'en', 'de'], the service returns a reasonable English match rather than defaulting to German @test

• When a user prefers ['es-MX'] and available locales are ['es', 'es-ES', 'en'], the service returns an appropriate Spanish variant @test

Implementation

@generates

API

/**
 * Matches user locale preferences against available content locales
 * using region-aware matching algorithms
 *
 * @param userLocales - Array of user-preferred locale codes in priority order
 * @param availableLocales - Array of locale codes for which content is available
 * @param defaultLocale - Default locale to use when no match is found
 * @returns The best matching locale code from availableLocales
 */
export function matchContentLocale(
  userLocales: string[],
  availableLocales: string[],
  defaultLocale: string
): string;

Dependencies { .dependencies }

@formatjs/intl-localematcher { .dependency }

Provides sophisticated locale matching with region-aware algorithms.