Volver al blog

Cómo organizar contenido bilingüe con Astro, MDX y Content Collections

La estructura que uso para publicar cada artículo en español e inglés sin duplicar rutas, metadatos ni lógica. También cuento qué simplifica y qué compromiso introduce.

Publicado
Lectura
8 minutos
Temas
Astro · MDX · i18n · SEO

Tener una web en dos idiomas parece sencillo mientras solo traduces la navegación. La cosa cambia cuando llegan los artículos, los proyectos, sus títulos, sus rutas y sus metadatos. Si cada parte resuelve el idioma por su cuenta, publicar algo nuevo acaba siendo una cadena de pasos fáciles de olvidar.

En este portfolio elegí guardar cada artículo en un único archivo MDX, con una versión en español y otra en inglés. Astro genera dos rutas para ese mismo contenido. No lo planteé como una solución universal de internacionalización, sino como una forma razonable de mantener un sitio personal que escribo y publico yo mismo.

La decisión tiene ventajas claras, pero también una limitación importante que no quiero esconder.

El contenido es bilingüe antes de que exista la página

Un artículo no solo tiene cuerpo. Tiene título, resumen, fecha, etiquetas y URL. El título y el resumen también deben estar en el idioma correcto cuando aparecen en el listado, en los resultados de búsqueda o al compartir un enlace.

Por eso la colección de posts define los campos comunes y permite una versión inglesa de los textos que se muestran fuera del cuerpo:

const posts = defineCollection({
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    title_en: z.string().optional(),
    slug_en: z.string(),
    summary: z.string(),
    summary_en: z.string().optional(),
    tags: z.array(z.string()).default([]),
    publishedAt: z.coerce.date(),
  }),
});

Esto no traduce nada automáticamente. Solo hace explícito qué datos necesita cada entrada. Si olvido una fecha o escribo un tipo de dato incorrecto, la validación ocurre durante el desarrollo o al generar la web, no después de publicar una página rota. Las Content Collections de Astro sirven precisamente para contenido con una estructura repetida y un esquema que se pueda comprobar. En cómo modelo contenido, componentes y metadatos con TypeScript profundizo en lo que ese contrato detecta y en lo que todavía hay que revisar fuera del tipado.

En una web con muchas personas editando contenido quizá separaría los idiomas desde el principio. Aquí, mantener ambos títulos en el mismo frontmatter me ayuda a revisar que salen a la vez y que no queda una ruta inglesa con el título español por descuido.

Un archivo por artículo y dos bloques de lectura

El cuerpo sigue la misma idea. Cada MDX contiene dos bloques consecutivos:

<div lang="es">

## La explicación en español

...

</div>

<div lang="en">

## The English version

...

</div>

No son dos versiones idénticas pegadas una debajo de otra. El inglés necesita otro ritmo, ejemplos y expresiones propias. A veces una frase que funciona en español no merece sobrevivir a la traducción. Mantenerlas juntas sí ayuda a no perder el hilo cuando actualizo un hecho, un enlace o un ejemplo técnico.

Las rutas de artículo renderizan la misma entrada, pero no reutilizan el slug. El identificador del archivo mantiene la URL española y el campo slug_en define una URL inglesa natural: /blog/astro-mdx-contenido-bilingue/ y /en/blog/astro-mdx-bilingual-content/. Cada ruta selecciona su título, resumen y datos estructurados. Al terminar el build, la integración strip-localized-content de astro.config.mjs elimina del HTML el bloque cuyo idioma no corresponde a la ruta. El archivo publicado contiene solo el cuerpo del idioma solicitado.

El compromiso está en el mantenimiento: los dos cuerpos siguen compartiendo archivo MDX y la integración de build depende del formato de sus bloques div con atributo lang. El CSS conserva una regla para ocultar el otro idioma durante desarrollo, pero en producción ese bloque ya se ha eliminado. Si añadiera más idiomas o una estructura más compleja, preferiría archivos separados por locale para evitar ese procesamiento posterior.

Las rutas tienen una única fuente de verdad

Duplicar páginas no es el problema. Duplicar reglas sí lo es.

Hay rutas estáticas que no comparten nombre entre idiomas, como /sobre-mi/ y /en/about/. Esas equivalencias viven en src/config/i18n.mjs. Los artículos y proyectos son dinámicos, así que sus rutas se construyen desde los datos de la colección mediante src/lib/routes.ts.

El helper recibe la entrada y el idioma, y devuelve la ruta pública correspondiente:

export const getPostPath = (post, locale) =>
  locale === 'en'
    ? `/en/blog/${post.data.slug_en}/`
    : `/blog/${post.id}/`;

No es una abstracción espectacular, pero quita trabajo repetido de los sitios donde un error tendría consecuencias visibles. La ruta dinámica pasa la alternativa exacta al selector de idioma y a las etiquetas hreflang; el sitemap usa el mismo helper. Cuando añado un artículo, su frontmatter contiene la relación y no tengo que mantener tres mapas distintos de URLs.

Astro también permite configurar su propio enrutado i18n. En este proyecto mantengo el mapa manual porque necesito nombres de rutas diferentes entre español e inglés y ya tenía una estructura de páginas estáticas clara. La documentación de Astro explica las dos piezas, el enrutado localizado y las colecciones, pero no obliga a encajar todos los proyectos en la misma forma de organizarse.

El índice revela una consecuencia de guardar ambos idiomas juntos

La eliminación del otro idioma al terminar el build no resuelve el índice. render() devuelve todos los encabezados del MDX antes de ese paso. Si usara esa lista sin filtrarla, el índice lateral de un artículo en español enseñaría también los títulos en inglés.

Por eso el proyecto cuenta los encabezados de cada bloque y entrega al índice únicamente los que pertenecen a la ruta actual. Es una función pequeña, pero representa bien el tipo de mantenimiento que introduce esta estructura. Cuando eliges almacenar dos versiones en una entrada, debes revisar todas las partes que leen el contenido, no solo el texto que se ve en pantalla.

Los bloques deben mantenerse consecutivos y con el mismo formato porque esa función depende de ello. No es una regla que impondría a cualquier equipo, pero sí una convención que conviene documentar mientras siga usando este enfoque.

El idioma también llega a los buscadores

Dos rutas útiles para una persona pueden ser confusas para un buscador si no quedan relacionadas. Cada página genera su canonical y declara las alternativas española e inglesa con hreflang. El sitemap repite esa relación para las páginas estáticas, los proyectos y los artículos.

He detallado esa parte en cómo implementé hreflang en una web bilingüe. Aquí lo relevante es que los metadatos no se añaden al final como una tarea de SEO. Salen del mismo mapa de rutas que usa la navegación. Es más difícil que la versión inglesa apunte a una URL equivocada cuando no hay que escribir esa URL a mano en cada página.

La estructura también conecta con el trabajo de SEO técnico del portfolio. Una canonical correcta o un sitemap actualizado sirven de poco si el contenido, las rutas y los alternates se mantienen por separado y terminan contradiciéndose.

Cuándo dejaría de usar esta estructura

No elegiría un único MDX bilingüe para cualquier sitio. Lo cambiaría si ocurriera alguna de estas cosas:

  • Un traductor o un equipo editorial necesitara trabajar sin tocar el texto del otro idioma.
  • Cada mercado tuviera artículos, ejemplos o calendarios de publicación distintos.
  • Añadiera más idiomas y el archivo dejara de ser fácil de revisar.
  • La estructura del contenido dejara de encajar con el procesamiento posterior del build.
  • Necesitara estados de traducción, revisiones o previsualizaciones propias de un CMS.

En ese contexto, dos colecciones por idioma o un CMS con entradas relacionadas darían más independencia. A cambio, habría que resolver la relación entre versiones, los slugs compartidos y los metadatos con el mismo cuidado.

Para este portfolio no buscaba demostrar que una arquitectura es “la correcta”. Buscaba que publicar un artículo en ambos idiomas fuera un proceso repetible, que no obligara a copiar componentes y que siguiera siendo comprensible dentro de unos meses. De momento, un MDX por pieza y unas pocas reglas explícitas cumplen mejor ese trabajo que una estructura más grande.