Internacionalización en Astro: enrutamiento i18n frente a traducción automática
Astro v3.5 introdujo enrutamiento i18n nativo: prefijos de URL como /fr/, /de/, detección de idioma y getRelativeLocaleUrl(). Es una infraestructura sólida. Pero el enrutamiento no es traducción. El enrutamiento i18n de Astro le dice a los visitantes a dónde ir; no traduce lo que ven cuando llegan. Este artículo cubre lo que realmente ofrece Astro i18n, lo que no, y cómo añadir traducción de contenido real.
Qué hace el enrutamiento i18n integrado de Astro
Desde la v3.5, Astro incluye un bloque de configuración i18n nativo en astro.config.mjs. Declarar tus locales ahí te da enrutamiento basado en URL de forma predeterminada:
Con esta configuración, Astro genera automáticamente rutas de URL con prefijo de locale: las páginas colocadas bajo src/pages/fr/ se sirven en /fr/about, /fr/pricing, y así sucesivamente. La capa de enrutamiento también ofrece dos helpers de URL:
getRelativeLocaleUrl(locale, path)— construye una ruta con prefijo de locale relativa a la raíz del sitio.getAbsoluteLocaleUrl(locale, path)— lo mismo, pero con el origen completo antepuesto; útil para etiquetas canónicas y sitemaps.- Detección de idioma mediante la cabecera
Accept-Languageen modo servidor (SSR): Astro puede redirigir a los visitantes a su locale preferido automáticamente.
Lo que no hace: traducir tu contenido. Activar el bloque de configuración i18n te da estructura de URL y helpers de enrutamiento. El contenido real en /fr/about aún necesita escribirse en francés, ya sea creando src/pages/fr/about.astro con texto traducido manualmente, o usando Content Collections con entradas por locale. La capa de enrutamiento es puramente estructural.
El enfoque tradicional: colecciones de contenido por locale
El patrón más habitual para sitios de Astro multilingües es combinar la capa de enrutamiento con directorios de contenido específicos por locale. Para un blog, esto significa estructurar tu colección de contenido por idioma:
Este enfoque funciona bien en condiciones específicas: el sitio es pequeño, un traductor dedicado se encarga de cada directorio de locale, y el contenido cambia con poca frecuencia. La estructura es explícita y el resultado es auditable: cada archivo traducido es un artefacto discreto con su propio historial de versiones.
La aritmética de mantenimiento se vuelve rápidamente en tu contra. Veinte páginas en cinco idiomas significan 100 archivos separados que mantener sincronizados. Cada vez que se actualiza la versión en inglés de una página, las cuatro variantes de locale se quedan atrás hasta que un traductor las alcanza. El desfase de contenido —donde la página en inglés se ha reescrito pero la versión en francés lleva seis meses obsoleta— es el modo de fallo más común de este enfoque. A escala, la sobrecarga de mantener la paridad de locale tiende a degenerar en descuido benigno.
Traducción automática: un script, todos los idiomas
La alternativa no requiere duplicación de contenido. Añade el script de Lingvit a tu layout de Astro antes de la etiqueta de cierre </body>:
Esa es la integración completa. A partir de ahí, Lingvit observa el DOM renderizado y lo traduce a los idiomas de destino que hayas activado en el panel. Vale la pena señalar algunas propiedades de este enfoque:
Funciona en todos los modos de salida de Astro
La salida estática (output: "static"), renderizada en servidor (output: "server") y el modo híbrido producen HTML que Lingvit puede traducir. El widget opera del lado del cliente después de que la página carga, por lo que el modo de salida no afecta a su funcionamiento.
Traduce los islands de Astro
Los islands construidos con React, Vue, Svelte o Solid se hidratan del lado del cliente y renderizan su salida en el DOM. El MutationObserver de Lingvit capta estos nodos a medida que aparecen, sin importar qué framework impulse el island ni qué directiva de hidratación (client:load, client:visible, etc.) se haya usado.
El contenido nuevo se traduce automáticamente
Cuando publicas una nueva entrada de blog o actualizas una página de destino, las versiones traducidas reflejan el cambio en la siguiente carga de página. No hay archivos de locale que actualizar ni cola de traductores que desbloquear.
Control editorial mediante el panel
Cualquier cadena traducida automáticamente puede revisarse y sustituirse desde el panel de Lingvit. Las sustituciones persisten: si corriges un nombre de producto o un término de marca en francés, esa corrección se aplica cada vez que aparece esa cadena.
¿Puedes combinar el enrutamiento i18n de Astro con la traducción automática?
Sí, y es el enfoque recomendado para sitios que cuidan el SEO. Los dos sistemas operan en capas diferentes y se complementan de forma limpia.
El enrutamiento integrado de Astro gestiona la estructura de URL. URL como /fr/about y /de/pricing son las que usan los buscadores al indexar contenido multilingüe: cada locale obtiene su propia URL rastreable, su propia canónica y sus propias señales hreflang. Esta es la base correcta para el SEO multilingüe, y la capa de enrutamiento de Astro la ofrece bien.
Lingvit gestiona la traducción real del contenido dentro de esas URL. En lugar de mantener un archivo separado src/pages/fr/about.astro con texto traducido a mano, mantienes un único archivo de origen y dejas que Lingvit traduzca su salida renderizada automáticamente. El resultado son URL indexadas por SEO por idioma con traducción de contenido automática y control editorial, sin duplicar tus archivos de origen.
Resumen de configuración combinada
- 1Configura el bloque
i18nde Astro enastro.config.mjscon tus locales de destino. Esto establece la estructura de URL. - 2Añade la etiqueta de script de Lingvit a
src/layouts/Layout.astroantes de</body>. Esto gestiona la traducción de contenido. - 3Mantén un único archivo de origen por página. Escribe y mantén el contenido en un idioma; Lingvit gestiona todas las variantes de locale automáticamente.
Cuándo usar cada enfoque
La elección no siempre es la traducción automática. Hay situaciones donde el enfoque tradicional de archivos de locale es claramente la decisión correcta:
Enrutamiento de Astro + archivos de locale
- ✓Sitio pequeño con un traductor dedicado por idioma
- ✓Contenido que rara vez cambia tras la publicación
- ✓Texto legal o regulado que requiere aprobación explícita por cadena
- ✓Proyecto de código abierto traducido por la comunidad
Enrutamiento de Astro + traducción automática
- ✓Sitios más grandes donde la paridad de archivos de locale es difícil de mantener
- ✓Contenido que se actualiza con frecuencia (blog, changelog, documentación)
- ✓Equipos sin recursos de traducción dedicados
- ✓Añadir idiomas a un sitio de Astro existente sin i18n
Preguntas frecuentes
- ¿Funciona la traducción automática con los islands de Astro?
- Sí. Los islands de React, Vue, Svelte y Solid se hidratan del lado del cliente y renderizan su salida en el DOM. El MutationObserver de Lingvit detecta este contenido a medida que aparece y lo traduce, sin importar qué framework use el island.
- ¿Funciona con la salida estática de Astro (SSG)?
- Sí. Lingvit se ejecuta completamente del lado del cliente después de que la página carga. Para la salida estática, el HTML se prediseña y Lingvit lo traduce en el navegador. Para SSR, Lingvit se ejecuta después de la hidratación. Ambos funcionan de forma idéntica desde la perspectiva de Lingvit.
- ¿Cómo interactúa Lingvit con el enrutamiento i18n integrado de Astro?
- Operan en capas diferentes. El enrutamiento de Astro gestiona la estructura de URL (/fr/, /de/) y las redirecciones. Lingvit gestiona la traducción real del contenido de texto. Puedes usar ambos juntos: Astro para el enrutamiento, Lingvit para el contenido.
- ¿Traduce las Content Collections de Astro?
- Sí. El contenido de Content Collections (MDX, Markdown) es renderizado a HTML por Astro en tiempo de compilación. Ese HTML se observa y traduce después mediante Lingvit del lado del cliente cuando la página carga en el navegador de un visitante.
Guías relacionadas
Añade idiomas a tu sitio de Astro
Funciona con proyectos de Astro estáticos, SSR e híbridos. Una etiqueta de script, sin duplicación de contenido.