💡 1. Qué es la internacionalización (i18n)

La internacionalización permite que tu web se muestre en varios idiomas, según:

la preferencia del usuario,
la configuración del navegador,
o la ruta del sitio (por ejemplo /es o /en).

En Astro puedes tener una estructura como esta:

src/pages/
├── es/
│   ├── index.astro
│   └── contacto.astro
└── en/
    ├── index.astro
    └── contact.astro

💡 Así, tusitio.com/es/ mostrará la versión en español y tusitio.com/en/ la versión en inglés.

🧱 2. Estructura básica de carpetas multilenguaje

Una forma sencilla de manejar varios idiomas es usar carpetas separadas por idioma dentro de src/pages.

Ejemplo:

src/pages/
├── es/
│   ├── index.astro
│   └── cursos.astro
└── en/
    ├── index.astro
    └── courses.astro

Luego puedes traducir cada archivo según el idioma.

📄 `src/pages/es/index.astro`

1---
2import BaseLayout from '../../layouts/BaseLayout.astro';
3---
4
5<BaseLayout title="Inicio">
6  <h1>Bienvenido a mi sitio web 🌟</h1>
7  <p>Aprende desarrollo web paso a paso.</p>
8  <a href="/en/">Ver en inglés</a>
9</BaseLayout>

📄 `src/pages/en/index.astro`

1---
2import BaseLayout from '../../layouts/BaseLayout.astro';
3---
4
5<BaseLayout title="Home">
6  <h1>Welcome to my website 🌟</h1>
7  <p>Learn web development step by step.</p>
8  <a href="/es/">Ver en español</a>
9</BaseLayout>

💡 De esta forma, cada idioma tiene su propia estructura de rutas limpia.

🌐 3. Cómo detectar el idioma automáticamente

Puedes usar el idioma del navegador para redirigir automáticamente al usuario.

Crea un archivo:

src/pages/index.astro

1---
2const idioma = Astro.request.headers.get("accept-language")?.split(",")[0];
3const esEspanol = idioma?.startsWith("es");
4
5Astro.redirect(esEspanol ? "/es/" : "/en/");
6---

👉 Si el navegador del usuario está en español, se lo envía a /es/, de lo contrario, a /en/.

🧩 4. Usar un archivo JSON para centralizar las traducciones

En proyectos grandes es mejor no duplicar páginas, sino usar diccionarios de texto.

Estructura:

src/i18n/
├── es.json
└── en.json

📄 `es.json`

1{
2  "title": "Bienvenido a mi sitio",
3  "subtitle": "Aprende desarrollo web paso a paso",
4  "button": "Comenzar"
5}

📄 `en.json`

1{
2  "title": "Welcome to my website",
3  "subtitle": "Learn web development step by step",
4  "button": "Get started"
5}

📄 `src/pages/[lang]/index.astro`

1---
2import BaseLayout from '../../layouts/BaseLayout.astro';
3import es from '../../i18n/es.json';
4import en from '../../i18n/en.json';
5
6const { lang } = Astro.params;
7const t = lang === 'es' ? es : en;
8---
9
10<BaseLayout title={t.title}>
11  <h1>{t.title}</h1>
12  <p>{t.subtitle}</p>
13  <button>{t.button}</button>
14</BaseLayout>

🟢 Esto permite que todas tus traducciones se centralicen en archivos JSON.

⚙️ 5. Estructura recomendada para proyectos medianos

src/
├── pages/
│   └── [lang]/
│       ├── index.astro
│       ├── about.astro
│       └── contact.astro
├── i18n/
│   ├── es.json
│   └── en.json
├── layouts/
│   └── BaseLayout.astro
└── components/
    └── LanguageSwitcher.astro

Y puedes crear un componente para cambiar de idioma fácilmente:

📄 `src/components/LanguageSwitcher.astro`

1---
2const { lang } = Astro.props;
3---
4
5<nav>
6  <a href="/es/" class={lang === 'es' ? 'active' : ''}>ES</a> |
7  <a href="/en/" class={lang === 'en' ? 'active' : ''}>EN</a>
8</nav>
9
10<style>
11  nav { text-align: right; margin: 1rem; }
12  a { text-decoration: none; color: #4f46e5; }
13  .active { font-weight: bold; }
14</style>

Luego lo importas en tu layout:

1<LanguageSwitcher lang={lang} />

🔄 6. URLs limpias con redirecciones automáticas

Puedes usar un pequeño script en astro.config.mjs o tu servicio de hosting (como Vercel o Netlify) para redirigir automáticamente / → /es/ o /en/.

Ejemplo básico en Vercel:

1{
2  "redirects": [
3    { "source": "/", "destination": "/es/", "permanent": true }
4  ]
5}

✅ Usa carpetas separadas por idioma o un sistema [lang]. ✅ Centraliza las traducciones en JSON o archivos de texto. ✅ Crea un componente “LanguageSwitcher”. ✅ Usa etiquetas <html lang="es"> o <html lang="en"> para mejorar el SEO. ✅ Cuida los hreflang en el <head> (para indicar idiomas a Google).