Si has intentado construir un sitio multilingüe con Astro, sabes lo complicado que es.

Astro es increíble para sitios estáticos. Rápido, flexible, amigable para desarrolladores. Pero en el momento en que necesitas dos o más idiomas, las cosas se complican rápidamente.

Terminas con archivos de páginas duplicados, prefijos de idioma hardcodeados, gestión manual de slugs y una pila creciente de soluciones improvisadas que hacen tu código más difícil de mantener con cada nueva página.

Nos topamos con este muro al construir otro.digital, un sitio completamente bilingüe inglés/español con URLs traducidas, una base de conocimientos, blog, casos de estudio y docenas de páginas. Las soluciones i18n existentes no funcionaban con la nueva API de Content Layer de Astro 5, requerían renderizado dinámico (eliminando la ventaja de rendimiento estático), o simplemente no manejaban la traducción de slugs en URLs.

Así que construimos la nuestra. Y hoy, la lanzamos como un paquete de código abierto: astro-i18n-next.

Qué hace

astro-i18n-next es una integración completa de internacionalización para sitios estáticos Astro 5. Una sola llamada a createI18n() en tu configuración de Astro, y obtienes:

Enrutamiento con URLs traducidas

Tu página en inglés /about/ automáticamente se convierte en /es/sobre/: sin rutas catch-all, sin archivos duplicados, sin cableado manual de rutas. Define las traducciones de slugs directamente en tus archivos de página:

// src/pages/about.astro
export const slugs = { es: 'sobre' };

La integración los descubre en tiempo de compilación y genera todas las rutas con prefijo de idioma por ti.

Una sola importación virtual

En lugar de importar helpers de cinco archivos diferentes, todo viene de un solo lugar:

import { t, localePath, switchLocalePath } from 'virtual:i18n';

t() para traducciones (basado en i18next), localePath() para construir URLs con reconocimiento de idioma, switchLocalePath() para selectores de idioma. Limpio, predecible, sin boilerplate.

Markdown multilingüe

Escribe ambos idiomas en un solo archivo markdown usando marcadores de idioma simples:

---
title:
  en: "Getting Started"
  es: "Primeros pasos"
---

Tu contenido en inglés aquí.

<!-- locale:es -->

Tu contenido en español aquí.

Esto funciona con la API de Content Layer de Astro 5 a través de un loader personalizado. Un archivo por pieza de contenido, no dos. Tu contenido se mantiene junto y sincronizado.

Traducción de slugs en colecciones de contenido

Para colecciones de contenido (posts de blog, artículos de la base de conocimientos, casos de estudio), define slugs traducidos en el frontmatter:

slugs:
  en: "email-marketing-fundamentals"
  es: "fundamentos-email-marketing"

La integración construye mapas de slugs automáticamente y localePath() los usa para generar URLs correctas en todas partes: páginas de índice, navegación, breadcrumbs, selectores de idioma.

i18next bajo el capó

Integración completa con i18next con claves de notación con puntos, cadenas de fallback y soporte de plugins. Si has usado i18next antes, funciona exactamente como esperarías. Si no, los valores predeterminados son sensatos y la curva de aprendizaje es suave.

Completamente estático, cero costo en tiempo de ejecución

Todo se resuelve en tiempo de compilación. Sin JavaScript del lado del cliente para enrutamiento. Sin detección de idioma en tiempo de ejecución en páginas estáticas. Tu sitio multilingüe es tan rápido como un sitio Astro de un solo idioma.

Por qué lo hicimos open source

Lo construimos para nosotros mismos, pero los problemas que resuelve no son exclusivos nuestros.

Cada agencia y desarrollador que construye sitios Astro multilingües se topa con los mismos muros: duplicación desordenada de archivos, traducción de slugs rota, colecciones de contenido que no se llevan bien con i18n, gestión manual de hreflang.

Preferimos aportar una solución sólida al ecosistema que ver a todos reinventar las mismas soluciones improvisadas.

El paquete tiene licencia MIT, está publicado en npm como @otrodigital/astro-i18n-next, y viene con documentación completa que cubre todo, desde la instalación hasta casos de uso avanzados.

Cómo empezar

Instala el paquete y su dependencia peer:

npm install @otrodigital/astro-i18n-next i18next

Agrégalo a tu configuración de Astro:

import { createI18n } from '@otrodigital/astro-i18n-next';

const i18n = createI18n({
  defaultLocale: 'en',
  locales: ['en', 'es'],
  translations: {
    en: { /* ... */ },
    es: { /* ... */ },
  },
});

export default defineConfig({
  integrations: [i18n.integration()],
});

Eso es todo. El sitio de documentación te guía por todo lo demás: rutas traducidas, contenido multilingüe, selectores de idioma, etiquetas SEO y más.

Qué viene después

Estamos usando esto activamente en nuestros propios sitios en producción, así que seguirá evolucionando basado en necesidades del mundo real. En el roadmap:

  • Inyección de rutas dinámicas: variantes de idioma automáticas para rutas [...slug] sin duplicación de archivos
  • Loader de contenido mejorado: soporte para MDX y esquemas de frontmatter más ricos
  • Feedback de la comunidad: si estás construyendo sitios Astro multilingües, queremos saber qué falta

El paquete está en GitHub. Issues, PRs y feedback son bienvenidos.

En resumen

La internacionalización no debería ser la parte más difícil de construir un sitio multilingüe. Con Astro manejando el renderizado estático y astro-i18n-next manejando la localización, puedes enfocarte en lo que realmente importa: crear gran contenido en cada idioma.

Lee la documentación →

Ve el código fuente en GitHub →

Instala desde npm →

¿Tienes preguntas o quieres ayuda configurando i18n para tu proyecto Astro? Inicia una conversación →