Traducir páginas en Astro

Traduces una página de Astro envolviendo su texto en t() y sus enlaces internos en href(), ambos leídos de Astro.locals. Todo se ejecuta en el servidor y un archivo de página sirve para cada idioma.

Antes de empezar

• La integración está instalada y <UniversallyHead /> está en tu diseño. Consulta Instala la integración de Astro.
• El proyecto tiene al menos un idioma de destino con su interruptor Activo activado.

Traduce texto con t()

1. Lee t de Astro.locals en el frontmatter de la página.
2. Pasa cada fragmento de texto de origen.

---
const { t } = Astro.locals;
---

<h1>{t('About us')}</h1>
<p>{t('We translate websites.')}</p>

t() toma tu texto de origen y devuelve el texto para el idioma que se está renderizando. El texto de origen es la clave, por lo que la cadena en tu código debe coincidir con la cadena de origen en el panel de control, carácter por carácter. Un espacio adicional o una coma cambiada la convierten en una cadena diferente.

Una cadena sin traducción aún devuelve el texto de origen, por lo que una página nunca se rompe mientras una traducción está en camino. La cadena se registra una vez y se informa después de la respuesta. En las páginas de idioma de origen, t() devuelve su argumento sin búsqueda ni informe.

Nunca llames a t(''). El traductor rechaza una cadena vacía y ese informe falla con un error registrado.

Localiza enlaces con href()

1. Lee href de Astro.locals.
2. Envuelve cada ruta interna.

---
const { t, href } = Astro.locals;
---

<a href={href('/pricing')}>{t('See pricing')}</a>

En una página en francés, /pricing se convierte en /fr/pricing, y la cadena de consulta y el hash se conservan. En el idioma de origen, la ruta vuelve sin cambios, porque el idioma de origen se sirve sin prefijo.

href() también devuelve estos sin cambios:

• una cadena vacía
• URLs relativas de protocolo que comienzan con //
• cualquier cosa que no comience con /: enlaces https: y mailto:, enlaces tel:, #fragmento, ?consulta y rutas relativas
• una ruta que ya lleva el prefijo, como /fr o /fr/pricing, por lo que llamarla dos veces no causa daño

Lee el idioma actual

Astro.locals.lang contiene el código de la variante del idioma que se está renderizando, en minúsculas: fr para francés (Francia), es-419 para español (México) y en-us en una página de origen en inglés (EE. UU.). Astro.locals contiene lang, t y href, y nada más.

Mantén el HTML en línea dentro de t()

Las etiquetas <strong> y <em> simples pueden permanecer dentro de la cadena. Renderiza el resultado con set:html:

---
const { t } = Astro.locals;
---

<p set:html={t('Wrap text in <strong>t()</strong> and keep your <em>markup</em> intact.')} />

Una cadena que contiene una etiqueta se normaliza antes de la traducción: los atributos en las etiquetas en línea se reemplazan por marcadores, y los elementos img y svg se vacían. Mantén las cadenas en texto plano, o en <strong> y <em> sin atributos.

Mantén <a> fuera de t():

---
const { t, href } = Astro.locals;
---

<p>{t('Compare every plan.')} <a href={href('/pricing')}>{t('See pricing')}</a></p>

La URL del enlace pertenece a un idioma, por lo que href() tiene que construirla. Una URL dentro del texto fuente también hace que la clave sea diferente en cada página que enlaza a otro lugar, lo que divide una traducción en muchas.

Pasa texto traducido a las islas

No hay t() del lado del cliente. Un componente que se hidrata en el navegador solo recibe texto traducido como props desde el archivo .astro:

---
import Counter from '../components/Counter.tsx';

const { t } = Astro.locals;
---

<Counter client:load label={t('Add one')} />

Traducir un sitio estático

Con output: 'static', la traducción ocurre durante la compilación:

1. Ejecuta la compilación. Carga cada idioma, renderiza cada página una vez, luego envía todas las cadenas que no tenía en una sola llamada.
2. Lee el final del registro. Si algo era nuevo, imprime una línea como 12 cadenas nuevas traducidas. Recompila para incluirlas.
3. Ejecuta la compilación de nuevo. Las nuevas cadenas ahora están en el HTML.

Un sitio estático no tiene código de servidor ejecutándose después de la compilación. Las ediciones del panel llegan a él solo cuando recompilas y redespliegas, como se describe en Actualizaciones de traducción en Astro.

Verificar que funcionó

Abre una página bajo un prefijo de destino, como /fr/about. El texto que envolviste en t() aparece traducido después de una recarga, y los enlaces creados con href() apuntan a rutas /fr/. El texto que no envolviste permanece en tu idioma fuente: nada en la página se traduce a menos que pase por t().

Si no funciona

• Una cadena permanece en el idioma fuente mientras el resto se traduce: su clave no coincide con la del panel. Compara el argumento de t() con la cadena fuente, carácter por carácter.
• Todas las cadenas permanecen en el idioma fuente: revisa el registro del servidor en busca de se alcanzó el límite de palabras. Consulta Solución de problemas de integración de Astro.