Una Guía Rápida para Localizar un Sitio Astro

¿Estás construyendo un sitio web multilingüe con Astro? Necesitas manejar dos desafíos distintos: organizar las páginas de contenido por idioma y traducir elementos de UI como botones y navegación. Esta guía te muestra exactamente cómo configurar localización tanto estática como dinámica en Astro, desde la configuración básica hasta funcionalidades listas para producción.

Configurando el Enrutamiento i18n de Astro para Contenido Estático

Configurando astro.config.mjs para Soporte Multilingüe

Comienza configurando el enrutamiento i18n integrado de Astro en tu archivo astro.config.mjs. Esto le dice a Astro qué idiomas soportas y cómo estructurar tus URLs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    routing: {
      prefixDefaultLocale: true // Usar /en/ para URLs en inglés
    }
  }
});

Establecer prefixDefaultLocale: true asegura que todos los idiomas usen patrones de URL consistentes (/en/about, /es/about), facilitando la gestión de enlaces y evitando conflictos de enrutamiento más adelante.

Creando Estructura de Carpetas Localizadas

Organiza tus páginas creando carpetas específicas por locale en src/pages/:

src/pages/
  en/
    index.astro
    about.astro
  es/
    index.astro
    about.astro
  fr/
    index.astro
    about.astro

Cada carpeta corresponde a un locale definido en tu configuración. Astro genera automáticamente las rutas correctas basándose en esta estructura.

Gestionando Localización Estática y Dinámica en Astro

Organizando Colecciones de Contenido por Locale

Para publicaciones de blog, documentación o cualquier colección de contenido, replica la misma estructura de locale:

src/content/
  blog/
    en/
      first-post.md
    es/
      first-post.md
    fr/
      first-post.md

Al consultar contenido, filtra por el locale actual:

import { getCollection } from 'astro:content';

const posts = await getCollection('blog', ({ id }) => {
  return id.startsWith(Astro.currentLocale + '/');
});

Implementando Rutas Dinámicas con Carpetas [locale]

En lugar de duplicar archivos de páginas para cada idioma, usa rutas dinámicas. Crea una carpeta [locale]:

src/pages/
  [locale]/
    index.astro
    about.astro
    blog/
      [slug].astro

En tus páginas, usa getStaticPaths() para generar rutas para todos los locales:

export function getStaticPaths() {
  return [
    { params: { locale: 'en' } },
    { params: { locale: 'es' } },
    { params: { locale: 'fr' } }
  ];
}

Manejando Strings Dinámicos de UI con Paraglide

Instalando y Configurando Paraglide para Astro

Mientras Astro maneja el enrutamiento de páginas, necesitas una solución para el texto de UI. Paraglide ofrece excelente soporte de TypeScript y tamaño mínimo de bundle:

npm install @inlang/paraglide-js @inlang/paraglide-astro
npx @inlang/paraglide-js init

Creando Archivos de Traducción y Claves de Mensajes

Almacena tus traducciones en messages/ en la raíz de tu proyecto:

// messages/en.json
{
  "nav.home": "Home",
  "nav.about": "About",
  "button.readMore": "Read more"
}

// messages/es.json
{
  "nav.home": "Inicio",
  "nav.about": "Acerca de",
  "button.readMore": "Leer más"
}

Importa y usa traducciones en tus componentes:

---
import * as m from '../paraglide/messages.js';
---

<nav>
  <a href={`/${Astro.currentLocale}`}>{m.nav_home()}</a>
  <a href={`/${Astro.currentLocale}/about`}>{m.nav_about()}</a>
</nav>

Construyendo un Selector de Idioma y Navegación

Usando getRelativeLocaleUrl() para URLs Limpias

Astro proporciona funciones auxiliares para generar URLs localizadas apropiadas. Siempre usa getRelativeLocaleUrl() en lugar de concatenación manual de strings:

import { getRelativeLocaleUrl } from 'astro:i18n';

const aboutUrl = getRelativeLocaleUrl(Astro.currentLocale, 'about');
const blogUrl = getRelativeLocaleUrl(Astro.currentLocale, 'blog/my-post');

Crea un componente selector de idioma:

---
import { getRelativeLocaleUrlList } from 'astro:i18n';

const localeUrls = getRelativeLocaleUrlList();
---

<select onchange="window.location.href = this.value">
  {localeUrls.map(url => {
    const locale = url.split('/')[1];
    return (
      <option value={url} selected={Astro.currentLocale === locale}>
        {locale.toUpperCase()}
      </option>
    );
  })}
</select>

Evitando Errores Comunes Como Rutas con Doble Prefijo

Ten cuidado con estos errores comunes:

1. Dobles prefijos: Al usar rutas dinámicas, limpia tus slugs para evitar URLs como /en/blog/en/my-post:

const cleanSlug = post.slug.replace(`${locale}/`, '');

2. Rutas de locale hardcodeadas: Siempre usa los helpers i18n de Astro en lugar de concatenación de strings
3. Locale faltante en enlaces: Cada enlace interno necesita localización apropiada

Funcionalidades Avanzadas de i18n en Astro

Configurando Idiomas de Respaldo

Configura respaldos para contenido no traducido:

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    fallback: {
      es: 'en',
      fr: 'en'
    },
    routing: {
      fallbackType: 'rewrite' // Mostrar contenido de respaldo sin redireccionar
    }
  }
});

Configurando Mapeo de Dominios para Producción

Para sitios de producción con dominios separados por idioma:

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    domains: {
      fr: 'https://fr.example.com',
      es: 'https://example.es'
    }
  }
});

Esto requiere renderizado del lado del servidor con el adaptador @astrojs/node o @astrojs/vercel.

Conclusión

Localizar un sitio Astro combina dos enfoques: enrutamiento i18n integrado para organización de contenido estático y librerías externas como Paraglide para strings dinámicos de UI. Comienza con la estructura de carpetas y configuración de enrutamiento, luego añade la gestión de traducciones. Recuerda usar los helpers de URL de Astro para evitar problemas comunes de enrutamiento, y considera respaldos y mapeo de dominios para despliegues de producción.

Preguntas Frecuentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.