Traducciones

Un sitio se puede publicar en varios idiomas. El primer idioma es el predeterminado y conserva sus URL; cada uno de los demás se sirve bajo su propio prefijo, como /es/, con su propia navegación, búsqueda, llms.txt y textos de interfaz. La cabecera recibe un selector de idioma, y una página aún sin traducir se queda en la navegación, marcada con el idioma en el que está escrita.

Configurar los idiomas

languages:
  - code: en
    label: English
  - code: es
    label: Español
  - code: zh
    label: 简体中文

Cada idioma acepta:

Sin languages, el sitio está solo en inglés y nada de lo que sigue se aplica. Un código listado dos veces, una clave de mensaje desconocida, o una sección cuyo prefijo queda bajo el prefijo de otro idioma (/es/…) hace fallar la compilación.

Traducir una página

Una traducción es un archivo junto a su original, nombrado con el código del idioma antes de .html. Se sirve bajo el prefijo del idioma y se empareja con el original por URL:

Un sufijo que no nombra ningún idioma configurado sigue formando parte del nombre, así que vite.config.html sigue siendo una página en inglés. Para guardar las traducciones en una carpeta propia, o para nombrar un archivo libremente, define el idioma en su head; un archivo que ya está bajo la carpeta del idioma no recibe el prefijo dos veces:

<meta name="language" content="es" />
<meta name="path" content="/guides/install/" />

---
language: es
path: /guides/install/
---

Una traducción solo se empareja con su original cuando ambos comparten una URL bajo el prefijo del idioma, así que da a un archivo renombrado el mismo path que su original. Un idioma que la configuración no lista hace fallar la compilación.

Traducir la configuración

El title, la description y el banner del sitio, el title de un enlace, y el title, el siteTitle y el siteDescription de una sección aceptan un texto para todos los idiomas o un mapa por código de idioma. Un idioma que falta en el mapa recibe el texto del idioma predeterminado:

title:
  en: Acme Docs
  es: Documentación de Acme
sections:
  - title: { en: Guide, es: Guía, zh: 指南 }
    prefix: /
  - title: Blog
    type: blog
    prefix: /blog/

Cada sección y cada enlace con un prefix se replica bajo el prefijo de cada idioma: el blog en español vive en /es/blog/, con su propio índice, páginas de etiquetas y feed RSS que listan las entradas en español y, después, las predeterminadas aún sin traducir. Una sección de changelog compila sus páginas en todos los idiomas, conservando las notas de versión tal como se escribieron; esas copias apuntan su URL canónica a la del idioma predeterminado y quedan fuera del sitemap. Una sección custom cuya url es una página del sitio lleva a la traducción de esa página, cuando el idioma abierto la tiene.

Páginas aún sin traducir

Un idioma lista cada página del idioma predeterminado de la que no tiene traducción, para que su navegación mantenga la misma forma. Esa entrada enlaza al original y lleva como insignia el código del idioma predeterminado, con "Aún sin traducir" como texto emergente. La página sin traducir se compila una sola vez, en su propio idioma; la búsqueda y llms.txt solo listan las páginas propias de cada idioma.

El selector de idioma enlaza cada idioma a la versión de esta página en él o, si no existe, a la página de inicio de ese idioma. Un idioma sin página de inicio propia, index.es.html, recibe una redirección de /es/ a su primera página; también el idioma predeterminado sin index.html. Los hosts que leen _redirects, como Cloudflare y Netlify, y htmlpress start redirigen en el servidor; los demás usan una página de redirección.

Textos de la interfaz

Los textos propios de htmlpress, como "En esta página", "Anterior" y "Editar esta página", y las fechas, vienen incluidos en inglés, alemán, español, francés, japonés, ruso y chino, y se eligen según el idioma del locale. Cualquiera de ellos se puede reemplazar por idioma:

languages:
  - code: en
    label: English
    messages:
      page.edit: Edit on GitHub
  - code: pt
    label: Português
    locale: pt-BR
    messages:
      toc.title: Nesta página
      nav.previous: Anterior
      nav.next: Próximo

Un idioma que htmlpress no incluye recurre al inglés para los textos que no define. Las claves son las de messages/en.yaml; los marcadores {name}, como {date}, se rellenan. date.format y date.months dan forma a cada fecha que se muestra a los lectores.

Qué recibe una página traducida

• <html lang> y, para los idiomas que se escriben de derecha a izquierda, <html dir="rtl">.
• Con site definido, un alternate hreflang por cada idioma que tiene la página, además de x-default apuntando a la versión del idioma predeterminado, y un og:locale.
• El índice de búsqueda de su idioma, _htmlpress/search.<code>.json, y una copia en Markdown y un llms.txt bajo el prefijo del idioma.
• El selector <htmlpress-language>, que un escape del layout coloca como cualquier otro elemento; se elimina en un sitio de un solo idioma.

Ver también

• Configuración: todas las claves de htmlpress.yaml.
• Secciones de artículos: cómo funcionan los prefijos y la correspondencia de secciones.
• Frontmatter: los metadatos propios de la página, incluido <meta name="language">.