Docs ejecutables de HTML: Atributo lang

Q: ¿Qué pongo en el atributo lang de html?

Un código de idioma del estándar BCP 47: es para español, en para inglés, fr para francés, ja para japonés. Añade una región solo cuando importe, como en es-MX, en-GB o pt-BR.

Q: ¿Uso lang="es" o lang="es-MX"?

Los dos son válidos. es basta para la mayoría de las páginas en español. Usa es-MX o es-ES cuando la variante regional importe, por ejemplo para el vocabulario, las fechas o la pronunciación de algunas palabras.

Q: ¿Cómo marco un texto en otro idioma?

Añade lang al elemento que lo rodea: bon appétit . Los lectores de pantalla cambian la pronunciación para esa frase, y el CSS puede darle estilo con :lang(fr).

Q: ¿Qué diferencia hay entre lang y hreflang?

lang dice en qué idioma está el contenido de un elemento. hreflang va en un enlace y dice en qué idioma está la página enlazada, que es como los sitios indican a los buscadores las otras versiones de idioma de una página.

Fijar el idioma de la página

Pon el atributo lang en el elemento <html>, con el código del idioma en el que está escrita tu página:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>lang</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <p>Hello! This page is in English.</p>
  <p id="out" style="color: #6b7280;"></p>
  <script>
    document.getElementById('out').textContent =
      'Page language: ' + document.documentElement.lang +
      '. Your browser language: ' + navigator.language + '.';
  </script>
</body>
</html>

El atributo no tiene ningún efecto visible en este párrafo, pero cambia cómo se trata la página: un lector de pantalla lo lee con una voz en inglés, el navegador lo usa para decidir si ofrece una traducción, y un corrector ortográfico puede usarlo para elegir el diccionario de inglés. Sin él, las herramientas tienen que adivinar, y un lector de pantalla configurado en otro idioma puede leer el texto en inglés con la pronunciación equivocada.

Códigos de idioma

El valor es una etiqueta de idioma del estándar BCP 47. La mayoría son un código de idioma de dos letras, seguido opcionalmente de una región o una escritura:

Código	Idioma
`en`	Inglés
`en-US`, `en-GB`	Inglés de Estados Unidos, del Reino Unido
`es`, `es-MX`	Español, español de México
`pt-BR`	Portugués de Brasil
`fr`, `de`, `it`	Francés, alemán, italiano
`ar`, `he`	Árabe, hebreo (de derecha a izquierda, ver más abajo)
`ja`, `ko`	Japonés, coreano
`zh-Hans`, `zh-Hant`	Chino en caracteres simplificados, tradicionales

Los códigos no distinguen mayúsculas de minúsculas, pero la convención es el idioma en minúsculas y la región en mayúsculas. Añade una región solo cuando la variante importe; es es un valor completo y correcto.

Cosas que cambia lang y que se ven

La mayoría de los efectos de lang son para el software, pero algunos aparecen en pantalla. Las comillas del elemento <q> siguen el idioma, y también las reglas de mayúsculas:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Visible effects</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; font-size: 18px; }
    td { padding: 4px 12px; border-bottom: 1px solid #e5e7eb; }
    .up { text-transform: uppercase; }
  </style>
</head>
<body>
  <table>
    <tr><td>English</td><td lang="en"><q>quote</q></td><td lang="en" class="up">istanbul</td></tr>
    <tr><td>French</td><td lang="fr"><q>quote</q></td><td lang="fr" class="up">istanbul</td></tr>
    <tr><td>German</td><td lang="de"><q>quote</q></td><td lang="de" class="up">istanbul</td></tr>
    <tr><td>Japanese</td><td lang="ja"><q>quote</q></td><td lang="ja" class="up">istanbul</td></tr>
    <tr><td>Turkish</td><td lang="tr"><q>quote</q></td><td lang="tr" class="up">istanbul</td></tr>
  </table>
</body>
</html>

Cada fila recibe su propio estilo de comillas. En la última columna, el mismo text-transform: uppercase da "ISTANBUL" en inglés e "İSTANBUL" en turco, porque el turco conserva el punto en la i mayúscula. Cambia el lang de la fila turca a en y el punto desaparece. La separación automática de palabras con guiones (hyphens: auto en CSS) también depende de lang: el navegador necesita saber el idioma para saber dónde se pueden cortar las palabras.

Marcar frases en otro idioma

lang funciona en cualquier elemento, no solo en <html>. Cuando una página en un idioma cita una frase en otro, envuelve la frase y dale su propio código. El CSS puede apuntar a idiomas con el selector :lang():

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Mixed languages</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    :lang(fr), :lang(es) { font-style: italic; color: #2563eb; }
  </style>
</head>
<body>
  <p>The chef said <span lang="fr">bon appétit</span> and left.</p>
  <p>Our team motto is <span lang="es">poco a poco</span>: little by little.</p>
</body>
</html>

Un lector de pantalla pasa a la pronunciación francesa para "bon appétit" y vuelve al inglés después. :lang(fr) también coincide con fr-CA y con cualquier otra variante del francés, y coincide con los elementos que heredan el idioma de un ancestro, algo que un selector de atributo como [lang="fr"] pasaría por alto.

Idiomas de derecha a izquierda: dir

El árabe, el hebreo, el persa y el urdu se escriben de derecha a izquierda. lang nombra el idioma; el atributo dir fija la dirección. Una página entera en árabe usa los dos en <html>:

<html lang="ar" dir="rtl">

Para una frase corta de derecha a izquierda dentro de una página de izquierda a derecha, pon los dos en el elemento que la rodea:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>dir</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    blockquote { border-inline-start: 4px solid #16a34a; margin: 12px 0; padding-inline-start: 12px; }
  </style>
</head>
<body>
  <p>The Arabic word for hello is <span lang="ar" dir="rtl">مرحبا</span>.</p>
  <blockquote lang="ar" dir="rtl">مرحبا بكم في الموقع</blockquote>
</body>
</html>

El blockquote se alinea a la derecha y su barra verde también pasa a la derecha, porque border-inline-start sigue la dirección. Usar propiedades lógicas como margin-inline-start en lugar de margin-left mantiene los diseños correctos en las dos direcciones.

lang vs hreflang

lang describe el contenido de un elemento. hreflang va en un enlace y describe la página a la que apunta. Los sitios con traducciones listan todas las versiones en el <head> para que los buscadores envíen a cada lector a la correcta:

<link rel="alternate" hreflang="en" href="https://example.com/">
<link rel="alternate" hreflang="de" href="https://example.com/de/">
<link rel="alternate" hreflang="x-default" href="https://example.com/">

Cada página traducida sigue fijando su propio lang en <html>: lang="de" en la alemana.

Errores comunes

Omitir lang. Muchas plantillas lo olvidan; ponlo junto al doctype en cada página.
Copiar lang="en" en las páginas traducidas. Una página en alemán marcada como inglés se lee con pronunciación inglesa. Haz que coincida con el contenido.
Usar un código de país como idioma. lang="jp" y lang="gr" no son japonés y griego; los códigos son ja y el.
Usar lang para fijar la dirección. lang="ar" por sí solo no hace que el texto vaya de derecha a izquierda. Añade dir="rtl".
Escribir lang="en_US". El separador es un guion: en-US.

Preguntas frecuentes

¿Qué hace el atributo lang en HTML?

Declara el idioma del contenido del elemento. Los lectores de pantalla lo usan para elegir la voz y la pronunciación correctas, los navegadores para ofrecer traducción, elegir las comillas y separar palabras con guiones, y algunos correctores ortográficos para elegir un diccionario.

¿Qué pongo en el atributo lang de html?

Un código de idioma del estándar BCP 47: es para español, en para inglés, fr para francés, ja para japonés. Añade una región solo cuando importe, como en es-MX, en-GB o pt-BR.

¿Uso lang="es" o lang="es-MX"?

Los dos son válidos. es basta para la mayoría de las páginas en español. Usa es-MX o es-ES cuando la variante regional importe, por ejemplo para el vocabulario, las fechas o la pronunciación de algunas palabras.

¿El atributo lang afecta al SEO?

Google ha dicho que detecta el idioma a partir del propio texto y no depende del atributo lang. Ponlo bien de todos modos: otros buscadores, las herramientas de traducción y los lectores de pantalla lo usan. Para enlazar las versiones traducidas de una página, usa enlaces hreflang.

¿Cómo marco un texto en otro idioma?

Añade lang al elemento que lo rodea: <span lang="fr">bon appétit</span>. Los lectores de pantalla cambian la pronunciación para esa frase, y el CSS puede darle estilo con :lang(fr).

¿Qué diferencia hay entre lang y hreflang?

lang dice en qué idioma está el contenido de un elemento. hreflang va en un enlace y dice en qué idioma está la página enlazada, que es como los sitios indican a los buscadores las otras versiones de idioma de una página.

Conceptos relacionados