Cómo trabajar con etiquetas de idioma como en-US y fr-CA

Comprende la estructura y el significado de las etiquetas de idioma BCP 47 para tomar mejores decisiones de internacionalización

Introducción

Las etiquetas de idioma son códigos estandarizados que identifican idiomas específicos y sus variaciones regionales. Estas etiquetas aparecen en todo el trabajo de internacionalización. Cuando detectas el idioma preferido de un usuario, el navegador devuelve etiquetas de idioma. Cuando formateas fechas o números, pasas etiquetas de idioma a la API Intl. Cuando cargas traducciones, usas etiquetas de idioma para determinar qué contenido mostrar.

Comprender cómo funcionan estas etiquetas te ayuda a tomar mejores decisiones sobre la selección de idioma, el comportamiento de respaldo y la organización del contenido. Esta lección explica la estructura de las etiquetas de idioma y te muestra cómo trabajar con ellas en JavaScript.

Qué son las etiquetas de idioma

Una etiqueta de idioma es una cadena como en, en-US o zh-Hans-CN que identifica un idioma y opcionalmente especifica el sistema de escritura y la región. Estas etiquetas siguen el estándar BCP 47, que es mantenido por el Internet Engineering Task Force y la Internet Assigned Numbers Authority.

BCP 47 significa Best Current Practice 47. El estándar define cómo construir etiquetas de idioma a partir de componentes más pequeños llamados subetiquetas. Cada subetiqueta representa un aspecto específico del idioma, como qué idioma se está usando, qué sistema de escritura utiliza o con qué país está asociado.

Todos los lenguajes de programación y bibliotecas de internacionalización usan etiquetas BCP 47. Esta consistencia significa que puedes usar los mismos identificadores de idioma en toda tu aplicación, desde la detección del navegador hasta el formateo del lado del servidor y los nombres de archivos de traducción.

Estructura de las etiquetas de idioma

Las etiquetas de idioma se componen de subetiquetas separadas por guiones. Las tres subetiquetas más comunes son idioma, script y región. Estas subetiquetas siempre aparecen en este orden específico cuando están presentes.

La subetiqueta de idioma va primero y es el único componente obligatorio. Utiliza un código de dos o tres letras de ISO 639. Por ejemplo, en representa inglés, fr representa francés y zh representa chino.

La subetiqueta de script va en segundo lugar cuando está presente. Utiliza un código de cuatro letras de ISO 15924 que identifica el sistema de escritura. Por ejemplo, Latn representa el alfabeto latino, Cyrl representa cirílico y Hans representa caracteres chinos simplificados.

La subetiqueta de región va al final cuando está presente. Utiliza un código de dos letras de ISO 3166-1 que normalmente representa un país. Por ejemplo, US representa Estados Unidos, CA representa Canadá y CN representa China.

Ejemplos de etiquetas de idioma comunes

Aquí hay ejemplos que demuestran los diferentes niveles de especificidad que puedes expresar con las etiquetas de idioma.

Etiquetas simples con solo un idioma:

  • en - inglés (sin región o script específico)
  • fr - francés (sin región o script específico)
  • es - español (sin región o script específico)

Etiquetas con idioma y región:

  • en-US - inglés como se usa en Estados Unidos
  • en-GB - inglés como se usa en Gran Bretaña
  • fr-CA - francés como se usa en Canadá
  • es-MX - español como se usa en México

Etiquetas con idioma, script y región:

  • zh-Hans-CN - chino usando caracteres simplificados en China
  • zh-Hant-TW - chino usando caracteres tradicionales en Taiwán
  • sr-Latn-RS - serbio usando script latino en Serbia
  • sr-Cyrl-RS - serbio usando script cirílico en Serbia

El nivel de especificidad que necesitas depende de tu aplicación. Si solo traduces texto, es posible que solo necesites idioma y región. Si trabajas con idiomas que utilizan múltiples sistemas de escritura, necesitas subetiquetas de script.

Convenciones de mayúsculas para etiquetas de idioma

Las etiquetas de idioma no distinguen entre mayúsculas y minúsculas. Las etiquetas en-US, EN-US, en-us y En-Us representan el mismo idioma. Sin embargo, existen patrones de capitalización convencionales que hacen las etiquetas más legibles.

Las subetiquetas de idioma convencionalmente utilizan letras minúsculas. Escribe en, no EN ni En.

Las subetiquetas de script convencionalmente utilizan mayúscula inicial con la primera letra en mayúscula. Escribe Latn, no latn ni LATN.

Las subetiquetas de región convencionalmente utilizan letras mayúsculas. Escribe US, no us ni Us.

Seguir estas convenciones hace que tus etiquetas sean más fáciles de leer y coincide con el formato utilizado en la documentación y especificaciones. Sin embargo, tu código debe aceptar etiquetas de idioma independientemente de la capitalización, porque el formato es oficialmente insensible a mayúsculas y minúsculas.

Análisis de etiquetas de idioma con JavaScript

JavaScript proporciona el constructor Intl.Locale para analizar etiquetas de idioma y extraer sus componentes. Este constructor acepta una cadena de etiqueta de idioma y devuelve un objeto con propiedades para cada subetiqueta.

const locale = new Intl.Locale("en-US");

console.log(locale.language);
// Output: "en"

console.log(locale.region);
// Output: "US"

El objeto Intl.Locale tiene propiedades para cada componente de la etiqueta de idioma. Estas propiedades devuelven undefined si la subetiqueta correspondiente no está presente en la etiqueta original.

const simple = new Intl.Locale("fr");
console.log(simple.language);
// Output: "fr"

console.log(simple.region);
// Output: undefined

Puedes analizar etiquetas con subetiquetas de script de la misma manera.

const complex = new Intl.Locale("zh-Hans-CN");

console.log(complex.language);
// Output: "zh"

console.log(complex.script);
// Output: "Hans"

console.log(complex.region);
// Output: "CN"

Esta capacidad de análisis es útil cuando necesitas tomar decisiones basadas en componentes específicos de una etiqueta de idioma. Por ejemplo, es posible que desees cargar diferentes fuentes según el script, o mostrar contenido diferente según la región.

Cuándo usar etiquetas específicas versus generales

Elegir el nivel adecuado de especificidad para las etiquetas de idioma depende de qué aspectos del idioma y la cultura necesita manejar tu aplicación.

Usa etiquetas solo de idioma como en o fr cuando tengas una única traducción que funcione para todos los hablantes de ese idioma. Esto es común en aplicaciones con presupuestos de localización limitados o idiomas con variación regional mínima.

Usa etiquetas de idioma y región como en-US o fr-CA cuando necesites tener en cuenta diferencias regionales en vocabulario, ortografía o convenciones culturales. El inglés británico y el inglés americano usan diferentes ortografías para muchas palabras. El francés canadiense y el francés europeo tienen vocabulario y expresiones diferentes.

Usa etiquetas de idioma, escritura y región como zh-Hans-CN cuando trabajes con idiomas que usan múltiples sistemas de escritura. El chino puede escribirse con caracteres simplificados o tradicionales. El serbio puede escribirse con alfabetos latino o cirílico. La subetiqueta de escritura distingue estas variantes.

Extracción de códigos de idioma para archivos de traducción

Muchos sistemas de traducción organizan los archivos por código de idioma. Puedes extraer solo el idioma y la región de una etiqueta de idioma completa para determinar qué archivo de traducción cargar.

const userLanguage = "zh-Hans-CN";
const locale = new Intl.Locale(userLanguage);

const translationKey = `${locale.language}-${locale.region}`;
console.log(translationKey);
// Output: "zh-CN"

Este enfoque funciona incluso si la etiqueta de idioma del usuario incluye componentes que no necesitas para la selección de archivos.

Algunas aplicaciones usan solo el código de idioma sin la región.

const userLanguage = "fr-CA";
const locale = new Intl.Locale(userLanguage);

const translationKey = locale.language;
console.log(translationKey);
// Output: "fr"

La estructura que elijas para los nombres de archivos de traducción debe coincidir con cómo extraes los componentes de las etiquetas de idioma.

Uso de etiquetas de idioma con la API Intl

La API Intl acepta etiquetas de idioma directamente en todos sus constructores. No necesitas analizar la etiqueta tú mismo a menos que necesites inspeccionar componentes específicos.

const date = new Date("2025-03-15");

const usFormat = new Intl.DateTimeFormat("en-US").format(date);
console.log(usFormat);
// Output: "3/15/2025"

const gbFormat = new Intl.DateTimeFormat("en-GB").format(date);
console.log(gbFormat);
// Output: "15/03/2025"

La API Intl utiliza la etiqueta de idioma para determinar qué convenciones de formato aplicar. Diferentes regiones formatean fechas, números y monedas de manera diferente, incluso cuando hablan el mismo idioma.

Puedes pasar la etiqueta de idioma que obtienes del navegador directamente a los constructores de Intl.

const userLanguage = navigator.language;
const formatter = new Intl.NumberFormat(userLanguage);

console.log(formatter.format(1234.5));
// Output varies by language
// For "en-US": "1,234.5"
// For "de-DE": "1.234,5"

Este es el patrón más común en la internacionalización del lado del cliente. Detecta el idioma del usuario y luego utiliza esa etiqueta de idioma en toda tu aplicación para formatear el contenido de manera apropiada.

Manejo de etiquetas de idioma no válidas

El constructor Intl.Locale lanza un RangeError si pasas una etiqueta de idioma no válida. Debes manejar este error cuando trabajes con etiquetas de idioma de fuentes no confiables.

try {
  const locale = new Intl.Locale("invalid-tag-format");
} catch (error) {
  console.log(error.name);
  // Output: "RangeError"

  console.log(error.message);
  // Output: "invalid language tag: invalid-tag-format"
}

La mayoría de las etiquetas de idioma de los navegadores son válidas, pero la entrada del usuario o fuentes de datos externas pueden contener etiquetas mal formadas. Envolver el constructor en manejo de errores evita que estas etiquetas no válidas bloqueen tu aplicación.