API Intl.DisplayNames

Convierte códigos de idioma, región, moneda y script en nombres legibles

Introducción

Tu aplicación tiene el código de país US, pero los usuarios ven el texto "Estados Unidos". Tienes el código de idioma fr, pero el selector de idioma muestra "Francés". Tienes el código de moneda EUR, pero la página de pago muestra "Euro".

Los navegadores mantienen datos extensos de localización para renderizar sus propias interfaces en diferentes idiomas. La API Intl.DisplayNames expone estos datos a JavaScript, convirtiendo códigos estandarizados en nombres legibles localizados para cualquier idioma.

Esto elimina la necesidad de bibliotecas de terceros o tablas de búsqueda personalizadas que requieren mantenimiento y localización. El navegador maneja tanto los datos como las traducciones.

Convertir códigos de región en nombres de países

El caso de uso más común implica convertir códigos de país ISO en nombres de países. Crea una instancia de DisplayNames con una configuración regional y tipo, luego llama al método of() con un código de país:

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States"
console.log(regionNames.of("GB")); // "United Kingdom"
console.log(regionNames.of("JP")); // "Japan"

El primer parámetro acepta un array de códigos de configuración regional siguiendo el estándar BCP 47. El navegador utiliza la primera configuración regional compatible del array. La opción type especifica qué tipo de código deseas convertir.

Los mismos códigos producen diferentes resultados cuando se localizan para diferentes idiomas:

const englishRegions = new Intl.DisplayNames(["en"], { type: "region" });
const japaneseRegions = new Intl.DisplayNames(["ja"], { type: "region" });
const spanishRegions = new Intl.DisplayNames(["es"], { type: "region" });

console.log(englishRegions.of("FR")); // "France"
console.log(japaneseRegions.of("FR")); // "フランス"
console.log(spanishRegions.of("FR")); // "Francia"

Este patrón funciona para construir selectores de países, visualizaciones de ubicación y cualquier elemento de interfaz que convierta códigos de país en nombres legibles.

Convertir códigos de idioma en nombres de idiomas

Los códigos de idioma utilizan el mismo patrón que los códigos de región. Establece type: "language" para convertir códigos de idioma en nombres de idiomas:

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en")); // "English"
console.log(languageNames.of("es")); // "Spanish"
console.log(languageNames.of("zh")); // "Chinese"
console.log(languageNames.of("ar")); // "Arabic"

Los códigos de idioma pueden incluir subtags regionales para variantes regionales:

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en-US")); // "American English"
console.log(languageNames.of("en-GB")); // "British English"
console.log(languageNames.of("fr-CA")); // "Canadian French"
console.log(languageNames.of("pt-BR")); // "Brazilian Portuguese"

Esto convierte códigos de idioma en nombres adecuados para selectores de idioma, interfaces de traducción y selectores de preferencias de idioma.

Mostrar nombres de idiomas en su propio idioma

Los selectores de idioma a menudo muestran cada idioma en su propio sistema de escritura. Crea una instancia separada de DisplayNames para cada idioma de destino:

const english = new Intl.DisplayNames(["en"], { type: "language" });
const french = new Intl.DisplayNames(["fr"], { type: "language" });
const japanese = new Intl.DisplayNames(["ja"], { type: "language" });
const arabic = new Intl.DisplayNames(["ar"], { type: "language" });

console.log(english.of("en")); // "English"
console.log(french.of("fr")); // "français"
console.log(japanese.of("ja")); // "日本語"
console.log(arabic.of("ar")); // "العربية"

Los usuarios reconocen su idioma más rápidamente cuando se muestra en su escritura nativa.

Convertir códigos de moneda en nombres de moneda

Los códigos de moneda siguen el estándar ISO 4217. Establece type: "currency" para convertir códigos de moneda de tres letras en nombres de moneda:

const currencyNames = new Intl.DisplayNames(["en"], { type: "currency" });

console.log(currencyNames.of("USD")); // "US Dollar"
console.log(currencyNames.of("EUR")); // "Euro"
console.log(currencyNames.of("GBP")); // "British Pound"
console.log(currencyNames.of("JPY")); // "Japanese Yen"

Los nombres de moneda se localizan según el idioma de visualización:

const englishCurrency = new Intl.DisplayNames(["en"], { type: "currency" });
const germanCurrency = new Intl.DisplayNames(["de"], { type: "currency" });
const japaneseCurrency = new Intl.DisplayNames(["ja"], { type: "currency" });

console.log(englishCurrency.of("EUR")); // "Euro"
console.log(germanCurrency.of("EUR")); // "Euro"
console.log(japaneseCurrency.of("EUR")); // "ユーロ"

Este patrón funciona para selectores de moneda en flujos de pago, paneles financieros e interfaces de conversión de moneda.

Convertir códigos de escritura en nombres de escritura

Los códigos de escritura utilizan el estándar ISO 15924. Establece type: "script" para convertir códigos de escritura de cuatro letras en nombres de escritura:

const scriptNames = new Intl.DisplayNames(["en"], { type: "script" });

console.log(scriptNames.of("Latn")); // "Latin"
console.log(scriptNames.of("Arab")); // "Arabic"
console.log(scriptNames.of("Cyrl")); // "Cyrillic"
console.log(scriptNames.of("Hans")); // "Simplified Chinese"
console.log(scriptNames.of("Hant")); // "Traditional Chinese"

Los nombres de escritura aparecen con menos frecuencia en las interfaces de usuario, pero se vuelven relevantes para sistemas de gestión de contenido multilingüe e interfaces de selección de idioma que distinguen entre sistemas de escritura.

Convertir códigos de calendario en nombres de calendario

Los sistemas de calendario varían entre culturas. Establece type: "calendar" para convertir identificadores de calendario en nombres de calendario:

const calendarNames = new Intl.DisplayNames(["en"], { type: "calendar" });

console.log(calendarNames.of("gregory")); // "Gregorian Calendar"
console.log(calendarNames.of("japanese")); // "Japanese Calendar"
console.log(calendarNames.of("buddhist")); // "Buddhist Calendar"
console.log(calendarNames.of("hebrew")); // "Hebrew Calendar"
console.log(calendarNames.of("islamic")); // "Islamic Calendar"
console.log(calendarNames.of("chinese")); // "Chinese Calendar"

Esto resulta útil para aplicaciones de programación, selectores de fecha con selección de sistema de calendario e interfaces de calendario internacionalizadas.

Convertir códigos de campos de fecha y hora en nombres de campos

Las interfaces de fecha y hora contienen campos etiquetados como año, mes y día. Establece type: "dateTimeField" para convertir identificadores de campo en nombres de campo localizados:

const dateFields = new Intl.DisplayNames(["en"], { type: "dateTimeField" });

console.log(dateFields.of("year")); // "year"
console.log(dateFields.of("month")); // "month"
console.log(dateFields.of("day")); // "day"
console.log(dateFields.of("hour")); // "hour"
console.log(dateFields.of("minute")); // "minute"
console.log(dateFields.of("weekday")); // "day of the week"
console.log(dateFields.of("dayPeriod")); // "AM/PM"
console.log(dateFields.of("timeZoneName")); // "time zone"

Estos nombres de campo se localizan según el idioma de visualización:

const englishFields = new Intl.DisplayNames(["en"], { type: "dateTimeField" });
const spanishFields = new Intl.DisplayNames(["es"], { type: "dateTimeField" });
const japaneseFields = new Intl.DisplayNames(["ja"], { type: "dateTimeField" });

console.log(englishFields.of("month")); // "month"
console.log(spanishFields.of("month")); // "mes"
console.log(japaneseFields.of("month")); // "月"

Los identificadores de campo válidos incluyen era, year, quarter, month, weekOfYear, weekday, day, dayPeriod, hour, minute, second y timeZoneName.

Este patrón permite crear selectores de fecha accesibles, interfaces de calendario y componentes de selección de hora con etiquetas correctamente localizadas.

Control de la longitud de visualización con opciones de estilo

La opción style controla el nivel de detalle de la salida. Tres valores producen diferentes longitudes:

const longNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "long",
});

const shortNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "short",
});

const narrowNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "narrow",
});

console.log(longNames.of("US")); // "United States"
console.log(shortNames.of("US")); // "US"
console.log(narrowNames.of("US")); // "US"

El estilo long (el predeterminado) produce el nombre completo. Los estilos short y narrow producen formas abreviadas cuando están disponibles, aunque no todos los códigos tienen variantes más cortas.

El estilo se vuelve más relevante con los nombres de idiomas:

const longLanguages = new Intl.DisplayNames(["en"], {
  type: "language",
  style: "long",
});

const shortLanguages = new Intl.DisplayNames(["en"], {
  type: "language",
  style: "short",
});

console.log(longLanguages.of("en-US")); // "American English"
console.log(shortLanguages.of("en-US")); // "US English"

Utiliza long para etiquetas completas en formularios e interfaces detalladas. Utiliza short o narrow para visualizaciones compactas como navegación móvil o elementos de interfaz con espacio limitado.

Manejo de variantes regionales de idioma con languageDisplay

Los códigos de idioma con subetiquetas de región pueden mostrarse como dialectos o como nombres de idioma estándar con calificadores regionales. La opción languageDisplay controla este comportamiento y solo se aplica cuando type: "language":

const dialectNames = new Intl.DisplayNames(["en"], {
  type: "language",
  languageDisplay: "dialect",
});

const standardNames = new Intl.DisplayNames(["en"], {
  type: "language",
  languageDisplay: "standard",
});

console.log(dialectNames.of("nl-BE")); // "Flemish"
console.log(standardNames.of("nl-BE")); // "Dutch (Belgium)"

console.log(dialectNames.of("en-AU")); // "Australian English"
console.log(standardNames.of("en-AU")); // "English (Australia)"

El valor dialect (el predeterminado) muestra las variantes regionales utilizando sus nombres comunes. El valor standard siempre muestra el idioma base con un calificador de región entre paréntesis.

Elige dialect cuando las variantes regionales tienen nombres conocidos que los usuarios reconocen. Elige standard para un formato consistente o cuando trabajes con combinaciones de idioma-región menos comunes.

Control del comportamiento de respaldo para códigos no válidos

El método of() recibe códigos que podrían no tener nombres de visualización correspondientes. La opción fallback determina qué sucede:

const withCodeFallback = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "code",
});

const withNoneFallback = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "none",
});

console.log(withCodeFallback.of("ZZ")); // "ZZ"
console.log(withNoneFallback.of("ZZ")); // undefined

El valor code (el predeterminado) devuelve el código de entrada cuando no existe un nombre de visualización. El valor none devuelve undefined para códigos sin mapear.

Utiliza code cuando siempre necesites un valor de cadena para mostrar, incluso si recurre al código mismo. Utiliza none cuando necesites detectar códigos no válidos y manejarlos explícitamente:

const regionNames = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "none",
});

function getRegionName(code) {
  const name = regionNames.of(code);
  if (name === undefined) {
    return "Unknown region";
  }
  return name;
}

console.log(getRegionName("US")); // "United States"
console.log(getRegionName("INVALID")); // "Unknown region"

Construir un componente selector de país

La API Intl.DisplayNames se integra directamente en los componentes de interfaz. Este ejemplo construye un selector de país que muestra los nombres de países en el idioma del usuario:

function CountrySelector({ locale, value, onChange }) {
  const regionNames = new Intl.DisplayNames([locale], { type: "region" });

  const countries = [
    "US",
    "GB",
    "CA",
    "AU",
    "FR",
    "DE",
    "JP",
    "CN",
    "BR",
    "IN",
  ];

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Select a country</option>
      {countries.map((code) => (
        <option key={code} value={code}>
          {regionNames.of(code)}
        </option>
      ))}
    </select>
  );
}

El componente recibe una prop de locale que controla el idioma de visualización. Cambiar la prop de locale vuelve a renderizar el menú desplegable con los nombres de países traducidos.

Construir un componente selector de idioma

Los selectores de idioma muestran cada idioma en su propio sistema de escritura. Crea una instancia de DisplayNames para cada idioma:

function LanguageSwitcher({ currentLocale, onLocaleChange }) {
  const languages = [
    { code: "en", name: "English" },
    { code: "es", name: "Español" },
    { code: "fr", name: "Français" },
    { code: "de", name: "Deutsch" },
    { code: "ja", name: "日本語" },
    { code: "zh", name: "中文" },
  ];

  return (
    <div>
      {languages.map((lang) => {
        const displayNames = new Intl.DisplayNames([lang.code], {
          type: "language",
        });
        const nativeName = displayNames.of(lang.code);

        return (
          <button
            key={lang.code}
            onClick={() => onLocaleChange(lang.code)}
            className={currentLocale === lang.code ? "active" : ""}
          >
            {nativeName}
          </button>
        );
      })}
    </div>
  );
}

Cada botón muestra el nombre del idioma en su propia escritura. Los usuarios reconocen su idioma inmediatamente independientemente del idioma actual de la interfaz.

Construir un componente selector de moneda

Los selectores de moneda se benefician de los nombres de moneda localizados. Este ejemplo crea un selector de moneda que se adapta al idioma de visualización:

function CurrencySelector({ locale, value, onChange }) {
  const currencyNames = new Intl.DisplayNames([locale], { type: "currency" });

  const currencies = ["USD", "EUR", "GBP", "JPY", "CNY", "CAD", "AUD"];

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Select currency</option>
      {currencies.map((code) => (
        <option key={code} value={code}>
          {code} - {currencyNames.of(code)}
        </option>
      ))}
    </select>
  );
}

El menú desplegable muestra tanto el código de moneda como el nombre de moneda localizado. Los usuarios en diferentes regiones ven los nombres de moneda en su propio idioma.

Obtener todos los valores admitidos

El método Intl.supportedValuesOf() devuelve arrays de todos los valores admitidos para cada tipo. Esto elimina las listas de códigos hardcodeadas:

const regions = Intl.supportedValuesOf("region");
console.log(regions); // ["AD", "AE", "AF", "AG", "AI", ...]

const languages = Intl.supportedValuesOf("language");
console.log(languages); // ["aa", "ab", "ae", "af", "ak", ...]

const currencies = Intl.supportedValuesOf("currency");
console.log(currencies); // ["AED", "AFN", "ALL", "AMD", ...]

const calendars = Intl.supportedValuesOf("calendar");
console.log(calendars); // ["buddhist", "chinese", "coptic", ...]

Construye selectores dinámicos que incluyan automáticamente todos los valores admitidos:

function UniversalCountrySelector({ locale, value, onChange }) {
  const regionNames = new Intl.DisplayNames([locale], { type: "region" });
  const allRegions = Intl.supportedValuesOf("region");

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Select a country</option>
      {allRegions.map((code) => (
        <option key={code} value={code}>
          {regionNames.of(code)}
        </option>
      ))}
    </select>
  );
}

Este componente incluye todos los códigos de región admitidos por el navegador sin mantener una lista hardcodeada.

Comprender los requisitos de formato de código

Cada tipo espera códigos en formatos específicos. Los formatos incorrectos producen un comportamiento de respaldo en lugar de nombres para mostrar.

Los códigos de región siguen ISO 3166-1 alpha-2 (dos letras) o UN M.49 (tres dígitos):

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States" (ISO 3166-1)
console.log(regionNames.of("001")); // "world" (UN M.49)
console.log(regionNames.of("150")); // "Europe" (UN M.49)

Los códigos de idioma siguen BCP 47, que combina códigos de idioma ISO 639 con subtags opcionales de región y escritura:

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en")); // "English"
console.log(languageNames.of("en-US")); // "American English"
console.log(languageNames.of("zh-Hans")); // "Simplified Chinese"
console.log(languageNames.of("zh-Hans-CN")); // "Simplified Chinese (China)"

Los códigos de moneda siguen ISO 4217 (tres letras):

const currencyNames = new Intl.DisplayNames(["en"], { type: "currency" });

console.log(currencyNames.of("USD")); // "US Dollar"
console.log(currencyNames.of("EUR")); // "Euro"

Los códigos de escritura siguen ISO 15924 (cuatro letras, en mayúsculas):

const scriptNames = new Intl.DisplayNames(["en"], { type: "script" });

console.log(scriptNames.of("Latn")); // "Latin"
console.log(scriptNames.of("Arab")); // "Arabic"

La comparación de códigos no distingue entre mayúsculas y minúsculas, pero seguir la capitalización estándar mejora la legibilidad:

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States"
console.log(regionNames.of("us")); // "United States"
console.log(regionNames.of("Us")); // "United States"

Compatibilidad y soporte del navegador

La API Intl.DisplayNames estuvo disponible en todos los navegadores principales en 2021. Las aplicaciones modernas pueden usarla sin polyfills.

La API base con los tipos language, region, script y currency tiene soporte universal. Los tipos calendar y dateTimeField aparecieron en versiones posteriores de los navegadores, pero tienen un amplio soporte a partir de 2025.

Verifica el soporte de funciones en tiempo de ejecución cuando sea necesario:

if (typeof Intl.DisplayNames !== "undefined") {
  const regionNames = new Intl.DisplayNames(["en"], { type: "region" });
  console.log(regionNames.of("US"));
} else {
  console.log("Intl.DisplayNames not supported");
}

Para aplicaciones que soportan navegadores más antiguos, recurre a tablas de búsqueda estáticas o bibliotecas de terceros cuando la API no esté disponible.

Optimización del rendimiento con caché

Crear instancias de DisplayNames tiene una sobrecarga mínima, pero las aplicaciones que convierten muchos códigos deben reutilizar instancias:

const cache = new Map();

function getDisplayNames(locale, type) {
  const key = `${locale}-${type}`;

  if (!cache.has(key)) {
    cache.set(key, new Intl.DisplayNames([locale], { type }));
  }

  return cache.get(key);
}

function getCountryName(locale, code) {
  const displayNames = getDisplayNames(locale, "region");
  return displayNames.of(code);
}

console.log(getCountryName("en", "US")); // "United States"
console.log(getCountryName("en", "FR")); // "France"
console.log(getCountryName("es", "US")); // "Estados Unidos"

La caché almacena instancias indexadas por configuración regional y tipo. Las llamadas posteriores reutilizan instancias existentes en lugar de crear nuevas.

Este patrón es más importante en rutas de código críticas que convierten cientos o miles de códigos, como renderizar grandes tablas de datos localizados.

Comparación con enfoques alternativos

Antes de la API Intl.DisplayNames, las aplicaciones usaban varios enfoques para convertir códigos en nombres.

Las tablas de búsqueda codificadas requerían mantenimiento y solo soportaban idiomas predeterminados:

const countryNames = {
  US: "United States",
  GB: "United Kingdom",
  FR: "France",
};

function getCountryName(code) {
  return countryNames[code] || code;
}

Este enfoque falla al agregar nuevos idiomas porque cada idioma necesita una tabla de búsqueda separada.

Las bibliotecas de terceros proporcionaban datos de localización pero aumentaban el tamaño del bundle:

import countries from "i18n-iso-countries";
import countriesEN from "i18n-iso-countries/langs/en.json";
import countriesES from "i18n-iso-countries/langs/es.json";

countries.registerLocale(countriesEN);
countries.registerLocale(countriesES);

console.log(countries.getName("US", "en")); // "United States"
console.log(countries.getName("US", "es")); // "Estados Unidos"

Las bibliotecas agregan kilobytes de datos al bundle y requieren actualizaciones cuando aparecen nuevos países o cambian los nombres.

La API Intl.DisplayNames elimina ambos problemas. El navegador mantiene los datos, manteniéndolos actualizados y eliminando las preocupaciones sobre el tamaño del paquete. Los datos admiten todos los idiomas que el navegador admite sin descargas adicionales.