¿Cómo verificar qué locale y opciones está utilizando realmente un formateador?

Introducción

Cuando creas un formateador Intl en JavaScript, las opciones que solicitas no siempre son las opciones que obtienes. El navegador realiza una negociación de locale, completa valores predeterminados y normaliza tu configuración para crear la configuración final. El método resolvedOptions() te permite inspeccionar exactamente qué está utilizando realmente el formateador.

Cada formateador en la API Intl tiene un método resolvedOptions(). Esto incluye Intl.DateTimeFormat, Intl.NumberFormat, Intl.ListFormat, Intl.PluralRules, Intl.Collator y otros. El método devuelve un objeto que contiene todos los detalles de configuración con los que terminó el formateador después de procesar tu entrada.

Este método es principalmente útil para depuración, comprender el comportamiento del navegador y detectar qué características están disponibles en el entorno actual.

La sintaxis básica

El método resolvedOptions() no toma parámetros. Lo llamas en cualquier instancia de formateador y devuelve un objeto.

const formatter = new Intl.DateTimeFormat('en-US');
const options = formatter.resolvedOptions();

console.log(options);
// {
//   locale: 'en-US',
//   calendar: 'gregory',
//   numberingSystem: 'latn',
//   timeZone: 'America/Los_Angeles',
//   ...
// }

El objeto devuelto siempre incluye como mínimo las propiedades locale, calendar y numberingSystem para formateadores de fecha, o locale y numberingSystem para formateadores de números. Las propiedades adicionales dependen de qué opciones especificaste y qué admite el tipo de formateador.

Por qué las opciones solicitadas difieren de las opciones resueltas

Hay tres razones principales por las que las opciones que solicitaste pueden diferir de las opciones resueltas.

Primero, la negociación de locale encuentra el locale disponible más adecuado cuando tu solicitud exacta no es compatible. Si solicitas de-AT pero el navegador solo tiene de, el locale resuelto será de.

const formatter = new Intl.DateTimeFormat('de-AT-u-ca-buddhist');
const options = formatter.resolvedOptions();

console.log(options.locale);
// Likely outputs: 'de-AT' or 'de'

console.log(options.calendar);
// Likely outputs: 'gregory' (if Buddhist calendar is not supported)

En segundo lugar, el navegador completa los valores predeterminados para cualquier opción que no especifiques. Estos valores predeterminados son específicos de la configuración regional.

const formatter = new Intl.NumberFormat('en-US');
const options = formatter.resolvedOptions();

console.log(options.style);
// Outputs: 'decimal'

console.log(options.minimumFractionDigits);
// Outputs: 0

console.log(options.maximumFractionDigits);
// Outputs: 3

En tercer lugar, el navegador normaliza ciertas opciones a su forma canónica. Si utilizas dateStyle o timeStyle, el navegador no incluye estas en las opciones resueltas. En su lugar, incluye las opciones de componentes individuales a las que se expanden.

Verificar la configuración regional que se está utilizando

La propiedad locale en las opciones resueltas te indica exactamente qué configuración regional está utilizando el formateador. Este es el resultado de la negociación de configuración regional.

const formatter = new Intl.DateTimeFormat(['zh-TW', 'zh-CN', 'en-US']);
const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs the first supported locale from the list

Si solicitas una configuración regional que incluye palabras clave de extensión Unicode, la configuración regional resuelta podría no incluir esas palabras clave si no fueron compatibles o se aplicaron como opciones separadas.

const formatter = new Intl.NumberFormat('en-US-u-nu-arab');
const options = formatter.resolvedOptions();

console.log(options.locale);
// Might output: 'en-US'

console.log(options.numberingSystem);
// Might output: 'arab' or 'latn' depending on support

Inspeccionar opciones de formato de fecha y hora

Para Intl.DateTimeFormat, las opciones resueltas incluyen detalles sobre qué componentes de fecha y hora se mostrarán y cómo.

const formatter = new Intl.DateTimeFormat('en-US', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  timeZone: 'America/New_York'
});

const options = formatter.resolvedOptions();

console.log(options.year);
// Outputs: 'numeric'

console.log(options.month);
// Outputs: 'long'

console.log(options.day);
// Outputs: 'numeric'

console.log(options.timeZone);
// Outputs: 'America/New_York'

console.log(options.calendar);
// Outputs: 'gregory'

Cuando utilizas dateStyle o timeStyle, esos atajos no se incluyen en las opciones resueltas. El navegador los expande en opciones de componentes individuales según la configuración regional.

const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'full'
});

const options = formatter.resolvedOptions();

console.log(options.dateStyle);
// Outputs: undefined

console.log(options.weekday);
// Outputs: 'long'

console.log(options.year);
// Outputs: 'numeric'

console.log(options.month);
// Outputs: 'long'

console.log(options.day);
// Outputs: 'numeric'

Si creas un formateador de fecha sin ninguna opción, las opciones resueltas te muestran lo que el navegador eligió como valores predeterminados para esa configuración regional.

const formatter = new Intl.DateTimeFormat('ja-JP');
const options = formatter.resolvedOptions();

console.log(options);
// Shows default date component options for Japanese locale

Inspeccionar opciones de formato de números

Para Intl.NumberFormat, las opciones resueltas te indican el estilo, la precisión, la agrupación y otros detalles de formato.

const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

const options = formatter.resolvedOptions();

console.log(options.style);
// Outputs: 'currency'

console.log(options.currency);
// Outputs: 'USD'

console.log(options.currencyDisplay);
// Outputs: 'symbol'

console.log(options.minimumFractionDigits);
// Outputs: 2

console.log(options.maximumFractionDigits);
// Outputs: 2

Puedes ver que aunque solo especificaste la moneda, el navegador completó los valores predeterminados para currencyDisplay y los dígitos de fracción.

Cuando utilizas opciones de redondeo, las opciones resueltas te muestran exactamente cómo se redondearán los números.

const formatter = new Intl.NumberFormat('en-US', {
  minimumSignificantDigits: 3,
  maximumSignificantDigits: 5
});

const options = formatter.resolvedOptions();

console.log(options.minimumSignificantDigits);
// Outputs: 3

console.log(options.maximumSignificantDigits);
// Outputs: 5

Inspección de otros tipos de formateadores

El método resolvedOptions() funciona de la misma manera en todos los formateadores Intl.

Para Intl.ListFormat, te muestra el tipo y el estilo.

const formatter = new Intl.ListFormat('en-US', {
  style: 'long',
  type: 'conjunction'
});

const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs: 'en-US'

console.log(options.style);
// Outputs: 'long'

console.log(options.type);
// Outputs: 'conjunction'

Para Intl.PluralRules, te muestra el tipo y los dígitos mínimos/máximos.

const formatter = new Intl.PluralRules('en-US', {
  type: 'ordinal'
});

const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs: 'en-US'

console.log(options.type);
// Outputs: 'ordinal'

console.log(options.minimumIntegerDigits);
// Outputs: 1

Casos de uso comunes para resolvedOptions()

El caso de uso más común es la depuración. Cuando la salida formateada no se ve como esperas, resolvedOptions() te ayuda a entender qué está haciendo realmente el formateador.

const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'medium'
});

console.log(formatter.format(new Date()));
// Check the output

console.log(formatter.resolvedOptions());
// See exactly which options produced that output

Otro caso de uso es la detección de características. Puedes verificar si un calendario específico, sistema de numeración u otra característica es compatible solicitándola y viendo qué se resolvió realmente.

const formatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic'
});

const options = formatter.resolvedOptions();

if (options.calendar === 'islamic') {
  console.log('Islamic calendar is supported');
} else {
  console.log('Islamic calendar is not supported, using ' + options.calendar);
}

También puedes usar resolvedOptions() para obtener las preferencias de configuración regional del usuario. Cuando creas un formateador sin argumento de configuración regional, el navegador usa las preferencias del usuario.

const formatter = new Intl.DateTimeFormat();
const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs: the user's preferred locale

console.log(options.timeZone);
// Outputs: the user's time zone

console.log(options.hourCycle);
// Outputs: the user's hour cycle preference (12 or 24 hour)

Finalmente, puedes usar las opciones resueltas para recrear un formateador idéntico. El objeto devuelto puede pasarse de vuelta al constructor.

const formatter1 = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

const options = formatter1.resolvedOptions();

const formatter2 = new Intl.NumberFormat(options.locale, options);

// formatter2 will format numbers identically to formatter1

Puntos clave

El método resolvedOptions() devuelve un objeto que contiene la configuración real que está usando un formateador. Esta configuración puede diferir de lo que solicitaste debido a la negociación de configuración regional, valores predeterminados y normalización.

Cada formateador Intl tiene este método. Lo llamas sin parámetros y recibes un objeto con propiedades como locale, calendar, numberingSystem y opciones específicas del formateador.

Usa resolvedOptions() principalmente para depurar el comportamiento del formateador, detectar características disponibles y entender cómo el navegador interpretó tus opciones. El objeto devuelto también puede usarse para recrear un formateador idéntico o inspeccionar las preferencias del usuario.