Region

Modern web applications serve global audiences, and JavaScript's native Internationalization API provides powerful tools for adapting content to different cultural contexts. The Intl.Locale.prototype.region property is a fundamental component of this system, enabling developers to extract and work with geographic region information from Unicode locale identifiers.

The region subtag represents the region of the world--typically a country--associated with a locale. This distinction is crucial because the same language can vary significantly across different countries. English in the United States differs from English in Great Britain in subtle but important ways: date formats, number formatting, and spelling conventions all depend on the regional context. By understanding and leveraging the region property, developers can create truly localized experiences without relying on heavy third-party libraries.

What Is the Region Property?

The region accessor property of Intl.Locale instances returns the region of the world (usually a country) associated with the locale. The region is represented as a two-letter ISO country code or a three-digit UN M49 region code, providing a standardized way to identify geographic areas.

Unicode Locale Identifier Structure

A complete locale identifier consists of several components:

• Language subtag: The primary language (e.g., en for English, zh for Chinese)
• Script subtag: The writing system (e.g., Latn for Latin, Cyrl for Cyrillic)
• Region subtag: The geographic area (e.g., US, GB, DE, JP)
• Variant subtags: Additional specific cultural or linguistic preferences

Common Region Examples

Handling Undefined Regions

The property returns undefined when no region subtag is present:

const genericLocale = new Intl.Locale("en");
console.log(genericLocale.region); // undefined

const regionalLocale = new Intl.Locale("en-US");
console.log(regionalLocale.region); // "US"

Adding Regions to Locale Objects

Regions can be incorporated into Intl.Locale objects through two primary mechanisms: the locale string syntax and the configuration object approach. Each method has its own use cases and advantages, and understanding both enables flexible internationalization implementations.

Using Locale Strings

The most straightforward method for adding a region involves including it directly in the locale identifier string passed to the Intl.Locale constructor. This approach mirrors the BCP 47 standard and provides a compact, readable way to specify locale components:

// Creating locales with regions in the identifier string
const usLocale = new Intl.Locale("en-Latn-US");
console.log(usLocale.region); // "US"

const gbLocale = new Intl.Locale("en-GB");
console.log(gbLocale.region); // "GB"

const deLocale = new Intl.Locale("de-DE");
console.log(deLocale.region); // "DE"

Regional variants can also use three-digit UN M49 region codes for broader geographic areas. For example, en-150 represents English used in Europe (region code 150), which groups multiple European countries together.

Using Configuration Objects

The Intl.Locale constructor also accepts an optional configuration object as a second argument, allowing programmatic specification of locale components:

// Creating locales with regions via configuration object
const frLocale = new Intl.Locale("fr-Latn", { region: "FR" });
console.log(frLocale.region); // "FR"

const brLocale = new Intl.Locale("pt", { region: "BR" });
console.log(brLocale.region); // "BR"

Configuration Precedence

When both the locale string and configuration object specify a region, the configuration object takes precedence:

const locale = new Intl.Locale("en-US", { region: "GB" });
console.log(locale.region); // "GB" - configuration overrides string

Practical Code Examples

Understanding the region property's theoretical aspects provides the foundation, but practical implementation is where its value becomes apparent. These examples demonstrate common patterns for leveraging the region property in web development projects.

Region-Based Date Formatting

function formatDateForLocale(date, locale) {
 const localeObj = new Intl.Locale(locale);
 const region = localeObj.region;
 
 let dateStyle, timeStyle;
 
 if (region === "US") {
 dateStyle = "MM/DD/YYYY";
 timeStyle = "h:mm a";
 } else if (region === "GB" || region === "DE" || region === "FR") {
 dateStyle = "DD/MM/YYYY";
 timeStyle = "HH:mm";
 } else if (region === "JP") {
 dateStyle = "YYYY/MM/DD";
 timeStyle = "HH:mm";
 } else {
 dateStyle = "medium";
 timeStyle = "short";
 }
 
 const formatter = new Intl.DateTimeFormat(locale, {
 dateStyle,
 timeStyle
 });
 
 return formatter.format(date);
}

console.log(formatDateForLocale(new Date(), "en-US"));
console.log(formatDateForLocale(new Date(), "en-GB"));

Currency and Number Formatting

function formatPrice(price, locale) {
 const localeObj = new Intl.Locale(locale);
 const region = localeObj.region;
 
 const regionToCurrency = {
 "US": "USD",
 "GB": "GBP",
 "DE": "EUR",
 "FR": "EUR",
 "JP": "JPY",
 "CN": "CNY",
 "CA": "CAD"
 };
 
 const currency = regionToCurrency[region] || "USD";
 
 return new Intl.NumberFormat(locale, {
 style: "currency",
 currency: currency
 }).format(price);
}

console.log(formatPrice(99.99, "en-US")); // "$99.99"
console.log(formatPrice(99.99, "en-GB")); // "GBP99.99"
console.log(formatPrice(99.99, "de-DE")); // "99,99 €"

Resource Selection Based on Region

function getRegionalResource(resourceMap, userLocale) {
 const userLocaleObj = new Intl.Locale(userLocale);
 const userRegion = userLocaleObj.region;
 
 // Try exact locale match first
 if (resourceMap[userLocale]) {
 return resourceMap[userLocale];
 }
 
 // Try matching region with same language
 if (userRegion) {
 const lang = userLocaleObj.language;
 const langRegionKey = `${lang}-${userRegion}`;
 
 if (resourceMap[langRegionKey]) {
 return resourceMap[langRegionKey];
 }
 }
 
 // Fallback to generic language
 const userLang = userLocaleObj.language;
 for (const key in resourceMap) {
 if (key.startsWith(userLang) && !key.includes("-")) {
 return resourceMap[key];
 }
 }
 
 return Object.values(resourceMap)[0];
}

Best Practices

Working effectively with the region property involves understanding common patterns and avoiding pitfalls that can lead to incorrect behavior or maintenance challenges. These best practices will help developers implement robust internationalization in web applications.

Validate Locale Input

User-provided locales or locales derived from HTTP headers may not always conform to expected formats. Applications should validate locales before creating Intl.Locale objects:

function createValidatedLocale(localeString) {
 try {
 const locale = new Intl.Locale(localeString);
 
 if (!locale.language) {
 throw new Error("Invalid locale: missing language");
 }
 
 return locale;
 } catch (error) {
 console.error(`Failed to create locale from "${localeString}"`);
 return new Intl.Locale("en");
 }
}

Handle Undefined Regions Explicitly

function getFormatterForLocale(localeString) {
 const locale = new Intl.Locale(localeString);
 
 if (!locale.region) {
 // Use language-only formatting
 return {
 formatDate: (date) => new Intl.DateTimeFormat(localeString).format(date),
 regionAware: false
 };
 }
 
 return {
 formatDate: (date) => new Intl.DateTimeFormat(localeString).format(date),
 regionAware: true,
 region: locale.region
 };
}

Cache Locale Objects for Performance

class LocaleCache {
 constructor() {
 this.cache = new Map();
 }
 
 get(localeString) {
 if (!this.cache.has(localeString)) {
 this.cache.set(localeString, new Intl.Locale(localeString));
 }
 return this.cache.get(localeString);
 }
 
 getRegion(localeString) {
 return this.get(localeString).region;
 }
}

Related APIs and Resources

The region property exists within a broader ecosystem of internationalization features in JavaScript. Understanding how it relates to other Intl APIs helps developers build comprehensive internationalization solutions for global web applications.

The Intl.supportedValuesOf() method (available in modern browsers) returns arrays of supported values for various locale features, enabling dynamic discovery of available options. Combined with the region property, these APIs enable comprehensive JavaScript internationalization for global web applications.

Sources

1. MDN Web Docs: Intl.Locale.prototype.region - Official documentation for the region accessor property
2. MDN Web Docs: Intl.Locale - Comprehensive Intl.Locale documentation
3. ECMAScript 2026 Internationalization API Specification - Official TC39 specification
4. W3C Intl Drafts: ECMAScript Internationalization API Guide - W3C guide to browser-native internationalization