acerca de HTML

Referencia de etiquetas

Etiqueta ruby en HTML: anotaciones de pronunciación

La etiqueta <ruby> asocia un texto con una anotación breve, como la pronunciación de una palabra. En una ficha de vocabulario japonés, permite conservar los kanji y añadir su lectura junto a ellos. Tanto la escritura como la anotación deben estar preparadas y comprobadas antes de incorporarlas al HTML.

Ejemplo mínimo de ruby

<ruby lang="ja">東京<rt>とうきょう</rt></ruby>

東京 es el texto base y とうきょう, dentro de <rt>, es su lectura: Tōkyō, Tokio en español. Puedes contrastar escritura y lectura en la entrada de 東京 del diccionario publicado en Kotobank. En un navegador con presentación ruby, la anotación suele verse más pequeña encima de la palabra; su posición depende de los estilos y del navegador.

El atributo lang="ja" identifica el idioma japonés y se hereda en <rt>. La anotación debe permanecer dentro de <ruby>. Si prefieres mostrarla en la misma línea, puedes escribir texto ordinario, como 東京 (とうきょう).

Sintaxis y contexto válido

Puedes colocar <ruby> donde se admite contenido de frase, como dentro de un párrafo, un elemento de lista o un encabezado. Escribe su apertura y su cierre: ninguna de esas etiquetas se puede omitir.

La forma sencilla consiste en una base seguida de su anotación <rt>. Puedes repetir esa secuencia para relacionar distintas bases y lecturas. La base puede contener texto y otros elementos de frase; no admite bloques como <p> o <table>. El modelo también permite una base que sea otro <ruby> sin más descendientes ruby, para anotaciones de dos niveles; no admite anidarlos indefinidamente.

Opcionalmente, sitúa <rp>(</rp> antes de <rt> y <rp>)</rp> después. Esos delimitadores ofrecen una alternativa para agentes que no presentan ruby. Los navegadores con esa presentación normalmente ocultan los <rp> y distribuyen la lectura junto a la base. Esta organización procede del modelo de contenido del HTML Living Standard.

Caso práctico: una ficha de vocabulario

Esta ficha muestra dos palabras con su lectura completa y significado en español. 学校, leído がっこう (gakkō), significa «escuela», según la entrada de 学校 de Digital Daijisen en Kotobank. La otra palabra es 東京, Tokio. Cada <rt> anota la palabra completa, sin repartir arbitrariamente sus sílabas entre caracteres.

Guarda este documento como vocabulario.html, en UTF-8, y ábrelo en el navegador. Incluye todo el CSS necesario y funciona sin JavaScript, archivos externos ni servidor.

<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Dos palabras japonesas</title>
    <style>
      body {
        margin: 1.5rem;
        font-family: sans-serif;
        line-height: 2.5;
        overflow-wrap: anywhere;
      }
      .vocabulario ruby { font-size: 1.5rem; }
      .vocabulario rt { font-size: 0.75em; }
      .arriba { ruby-position: over; }
      .abajo { ruby-position: under; }
    </style>
  </head>
  <body>
    <h1>Vocabulario japonés</h1>
    <ul class="vocabulario">
      <li>
        <ruby class="arriba" lang="ja">東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp></ruby>
        — Tokio.
      </li>
      <li>
        <ruby class="abajo" lang="ja">学校<rp>(</rp><rt>がっこう</rt><rp>)</rp></ruby>
        — Escuela.
      </li>
    </ul>
    <p>Lecturas: Tokio se lee Tōkyō; escuela se lee gakkō.</p>
  </body>
</html>

Con soporte para los valores usados de ruby-position, la lectura de Tokio aparece encima y la de escuela debajo. Los paréntesis no se ven. El espacio entre líneas evita que las anotaciones choquen con las líneas vecinas; la frase final proporciona las lecturas también en texto ordinario.

Prueba estas variaciones:

  1. Intercambia las clases arriba y abajo: cambia la posición, pero cada lectura conserva su relación con la misma base.
  2. Retira el CSS: permanecen las palabras y anotaciones, con la presentación predeterminada del navegador.
  3. Selecciona una palabra y su lectura con el ratón, o con la selección de texto por teclado del navegador, y pégalas en un editor. Comprueba qué incluye la copia: no presupongas que todos los navegadores copian solo la base ni que conservan la disposición visual.
  4. Elimina los dos <rp> de una palabra: en la presentación ruby no cambia su lectura, pero pierdes los delimitadores de la alternativa en línea.

Para examinar esa alternativa en un navegador moderno, añade temporalmente al final de <style>:

.vocabulario ruby,
.vocabulario rt,
.vocabulario rp {
  display: inline;
  font-size: inherit;
}

Verás 東京(とうきょう) y 学校(がっこう) en línea, junto a sus significados. Estas reglas permiten observar la alternativa en tu navegador; no reproducen todas las características de un navegador antiguo.

Atributos, CSS y accesibilidad

<ruby> no tiene atributos específicos. Admite atributos globales, como lang, id y class. Usa lang para identificar el idioma real de cada fragmento; si una anotación está en otro idioma, puedes indicarlo en el propio <rt>.

ruby-position es una propiedad de CSS, no un atributo HTML. Sus valores over y under colocan las anotaciones encima y debajo en escritura horizontal; en escritura vertical corresponden a lados distintos, como explica el módulo de CSS Ruby. Cambiar tamaño o posición no convierte una anotación en otro tipo de contenido.

No garantices que un lector de pantalla anuncie siempre base y lectura de la misma manera. Los mapeos de accesibilidad de HTML para ruby distinguen la exposición accesible de la presentación visual. Cuando esa ayuda sea esencial, ofrece una explicación textual, como en la ficha, y comprueba la combinación de navegador y tecnología de asistencia de tu audiencia. lang aporta contexto lingüístico; no activa audio ni asegura una voz concreta.

Errores y etiquetas relacionadas

  • Usarlo solo para texto pequeño. Elige CSS si únicamente necesitas ajustar el tamaño; ruby expresa una relación entre base y anotación.
  • Confundir anotación y exponente. Para x², <sup> representa un superíndice. <ruby> no reemplaza a <sup> ni representa por sí mismo una operación matemática.
  • Colocar <rt> fuera de <ruby>. La anotación debe ser hija de su contenedor. Consulta la guía de <rt> para la relación con la base y la guía de <rp> para los delimitadores.

¿Ruby sirve solo para japonés? No. Las ayudas de lectura japonesas, conocidas como furigana, son un uso habitual, pero también puedes anotar textos de otros idiomas o añadir otras anotaciones breves. Elige el elemento por esa relación, sin limitarlo a un sistema de escritura.

Compatibilidad y fuentes

Consulta del 3 de octubre de 2026: MDN clasifica <ruby> como ampliamente disponible. El soporte del elemento y el de su tipografía son cuestiones distintas: MDN sitúa ruby-position en Baseline 2024, desde diciembre de 2024, y advierte que algunos valores tienen soporte variable. Prueba los valores concretos en los navegadores de tu audiencia; no deduzcas el soporte de todos ellos a partir de la etiqueta.

La definición normativa de <ruby> fija significado, contexto y modelo de contenido. La referencia de MDN sobre <ruby> complementa los ejemplos y los datos de compatibilidad.