Traducir tu sitio Astro + Vanilla JS con Intlayer | Internacionalización (i18n)

Tabla de Contenidos

¿Por qué Intlayer en lugar de alternativas?

En comparación con soluciones principales como astro-i18n o i18next, Intlayer es una solución que viene con optimizaciones integradas como:

Guía paso a paso para configurar Intlayer en Astro + Vanilla JS

Consulta la plantilla de aplicación en GitHub.

1. 1

   Instalar dependencias

   Instala los paquetes necesarios utilizando tu gestor de paquetes preferido:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npx intlayer init --interactive
   

   la bandera --interactive es opcional. Usa intlayer-cli init si eres un agente de IA.

   Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install intlayer astro-intlayer vanilla-intlayer
   

   • intlayer El paquete core que proporciona herramientas de i18n para la gestión de la configuración, traducciones, declaración de contenidos, transpilación y comandos CLI.

   • astro-intlayer Incluye el plugin de integración de Astro para conectar Intlayer con el bundler Vite, así como el middleware para detectar el idioma preferido del usuario, gestionar cookies y manejar redirecciones de URL.

   • vanilla-intlayer Paquete para integrar Intlayer con aplicaciones de Vanilla JavaScript / TypeScript. Proporciona un singleton pub/sub (IntlayerClient) y helpers basados en callbacks (useIntlayer, useLocale, etc.) permitiendo que cualquier parte de tus etiquetas <script> de Astro responda a los cambios de idioma sin necesidad de un framework.

2. 2

   Configurar tu proyecto

   Crea un archivo de configuración para definir los idiomas de tu aplicación:

   intlayer.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Tus otros idiomas
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   A través de este archivo de configuración, puedes configurar URLs localizadas, redirecciones de middleware, nombres de cookies, ubicación y extensiones de las declaraciones de contenido, desactivar los logs de Intlayer en la consola, y más. Para una lista completa de los parámetros disponibles, consulta la documentación de configuración.

3. 3

   Integrar Intlayer en tu configuración de Astro

   Añade el plugin intlayer a tu configuración de Astro. Para Vanilla JS, no se requiere ninguna integración de framework de UI adicional.

   astro.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer()],
   });
   

   El plugin de integración intlayer() se utiliza para integrar Intlayer con Astro. Asegura la generación de los archivos de declaración de contenido y los vigila en modo desarrollo. Define las variables de entorno de Intlayer dentro de la aplicación Astro y proporciona alias para optimizar el rendimiento.

4. 4

   Declarar tu contenido

   Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

   src/app.content.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       greeting: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
       }),
       description: t({
         en: "Welcome to my multilingual Astro site.",
         fr: "Bienvenue sur mon site Astro multilingue.",
         es: "Bienvenido a mi sitio Astro multilingüe.",
       }),
       switchLocale: t({
         en: "Switch language:",
         fr: "Changer de langue :",
         es: "Cambiar idioma:",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   Las declaraciones de contenido pueden definirse en cualquier lugar de tu aplicación, siempre que estén incluidas en el contentDir (por defecto ./src) y coincidan con la extensión de los archivos de declaración de contenido (por defecto .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Para más información, consulta la documentación de declaración de contenido.

5. 5

   Usar el contenido en Astro

   Para Vanilla JS, todo el renderizado del lado del servidor se realiza utilizando getIntlayer directamente dentro de los archivos .astro. Posteriormente, un bloque <script> inicializa vanilla-intlayer en el cliente para manejar el cambio de idioma.

   src/pages/[...locale]/index.astro

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   ---
   import {
     getIntlayer,
     getLocaleFromPath,
     getLocalizedUrl,
     getPrefix,
     getLocaleName,
     localeMap,
     locales,
     defaultLocale,
     getPathWithoutLocale,
     type LocalesValues,
   } from "intlayer";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
   const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
   const { greeting, description, switchLocale } = getIntlayer("app", locale);
   ---
   
   <!doctype html>
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{greeting}</title>
   
       <!-- Enlace Canónico -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Enlaces Hreflang -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <main>
         <h1 id="greeting">{greeting}</h1>
         <p id="description">{description}</p>
   
         <div class="locale-switcher">
           <span class="switcher-label">{switchLocale}</span>
           <div class="locale-buttons">
             {
               locales.map((localeItem) => (
                 <a
                   href={localeItem === locale ? undefined : getLocalizedUrl(pathWithoutLocale, localeItem)}
                   class={`locale-btn ${localeItem === locale ? "active" : ""}`}
                   data-locale={localeItem}
                   aria-disabled={localeItem === locale}
                 >
                   {getLocaleName(localeItem)}
                 </a>
               ))
             }
           </div>
         </div>
       </main>
     </body>
   </html>
   

   Si desea utilizar su contenido en un atributo de cadena, como alt, title, href, aria-label, etc., puede utilizar el valor de la función, como:

   tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   <img src={content.image.src.value} alt={content.image.value} />
   <img src={content.image.src.toString()} alt={content.image.toString()} />
   <img src={String(content.image.src)} alt={String(content.image)} />
   

   Nota sobre la configuración de rutas: La estructura de directorios que utilices depende del ajuste middleware.routing en intlayer.config.ts:

   • prefix-no-default (por defecto): mantiene el idioma por defecto en la raíz (sin prefijo) y añade prefijos a los demás. Usa [...locale] para capturar todos los casos.
   • prefix-all: todos los URLs tienen prefijo de idioma. Puedes usar el estándar [locale] si no necesitas manejar la raíz por separado.
   • search-param o no-prefix: no se necesitan directorios de idioma. El idioma se maneja a través de parámetros de consulta o cookies.

6. 6

   Añadir funcionalidad de cambio de idioma

   En Astro con Vanilla JS, el selector de idioma se renderiza como enlaces normales en el servidor y se hidrata en el cliente a través de un bloque <script>. Cuando un usuario hace clic en un enlace de idioma, vanilla-intlayer establece la cookie de idioma mediante setLocale antes de navegar a la URL localizada.

   src/pages/[...locale]/index.astro

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   <!-- Consulta el marcado del servidor en el Paso 5 anterior -->
   
   <script>
     import { installIntlayer, useLocale } from "vanilla-intlayer";
     import { getLocaleFromPath, getLocalizedUrl, type LocalesValues } from "intlayer";
   
     // Inicializar Intlayer en el cliente con el idioma de la URL actual
     const locale = getLocaleFromPath(window.location.pathname);
     installIntlayer({ locale: locale as LocalesValues });
   
     const { setLocale } = useLocale({
       onLocaleChange: (newLocale: LocalesValues) => {
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   
     // Vincular eventos de clic a los enlaces del selector de idioma
     const localeLinks = document.querySelectorAll("[data-locale]");
     localeLinks.forEach((link) => {
       link.addEventListener("click", (e) => {
         const localeValue = link.getAttribute("data-locale") as LocalesValues;
         if (localeValue && localeValue !== locale) {
           e.preventDefault();
           setLocale(localeValue);
         }
       });
     });
   </script>
   

   Nota sobre la persistencia: installIntlayer inicializa el singleton de Intlayer con el idioma definido por el servidor. useLocale con onLocaleChange asegura que la cookie de idioma se establezca a través del middleware antes de la navegación, para que la preferencia del usuario se recuerde en futuras visitas.

   Nota sobre la mejora progresiva: Los enlaces del selector funcionan como etiquetas <a> estándar incluso sin JavaScript. Si JS está disponible, las llamadas a setLocale actualizan la cookie antes de navegar, permitiendo que el middleware realice la redirección correcta.

7. 7

   Sitemap y Robots.txt

   Intlayer ofrece utilidades para crear dinámicamente tu sitemap localizado y tus archivos robots.txt.

   Sitemap

   Intlayer viene con un generador de sitemap integrado para ayudarte a crear fácilmente un sitemap para tu aplicación. Maneja las rutas localizadas y agrega los metadatos necesarios para los motores de búsqueda.

   El sitemap generado por Intlayer admite el espacio de nombres xhtml:link (Hreflang XML Extensions). A diferencia de los generadores de sitemap predeterminados que solo enumeran URL sin procesar, Intlayer crea automáticamente los enlaces bidireccionales necesarios entre todas las versiones de idioma de una página (por ejemplo, /about, /about?lang=fr y /about?lang=es). Esto garantiza que los motores de búsqueda indexen y sirvan correctamente la versión de idioma adecuada a la audiencia adecuada.

   Crea src/pages/sitemap.xml.ts para generar un sitemap que incluya todas tus rutas localizadas.

   src/pages/sitemap.xml.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { APIRoute } from "astro";
   import { generateSitemap, type SitemapUrlEntry } from "intlayer";
   
   const pathList: SitemapUrlEntry[] = [
     { path: "/", changefreq: "daily", priority: 1.0 },
     { path: "/about", changefreq: "monthly", priority: 0.7 },
   ];
   
   const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
   
     return new Response(xmlOutput, {
       headers: { "Content-Type": "application/xml" },
     });
   };
   

   Robots.txt

   Crea src/pages/robots.txt.ts para controlar el rastreo de los motores de búsqueda.

   src/pages/robots.txt.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { APIRoute } from "astro";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
   
   export const GET: APIRoute = ({ site }) => {
     const robotsTxt = [
       "User-agent: *",
       "Allow: /",
       ...disallowedPaths.map((path) => `Disallow: ${path}`),
       "",
       `Sitemap: ${new URL("/sitemap.xml", site).href}`,
     ].join("\n");
   
     return new Response(robotsTxt, {
       headers: { "Content-Type": "text/plain" },
     });
   };
   

8. 15

   Extraer el contenido de tus componentes

   Opcional

   Si tienes una base de código existente, transformar miles de archivos puede llevar mucho tiempo.

   Para facilitar este proceso, Intlayer propone un compilador / extractor para transformar tus componentes y extraer el contenido.

   Para configurarlo, puedes agregar una sección compiler en tu archivo intlayer.config.ts :

   intlayer.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     // ... Resto de tu configuración
     compiler: {
       /**
        * Indica si el compilador debe estar habilitado.
        */
       enabled: true,
   
       /**
        * Define la ruta de los archivos de salida
        */
       output: ({ fileName, extension }) => `./${fileName}${extension}`,
   
       /**
        * Indica si los componentes deben guardarse después de ser transformados. De esa manera, el compilador se puede ejecutar solo una vez para transformar la aplicación y luego se puede eliminar.
        */
       saveComponents: false,
   
       /**
        * Prefijo de clave de diccionario
        */
       dictionaryKeyPrefix: "",
     },
   };
   
   export default config;
   

   Comando de extracciónCompilador Babel

   Ejecuta el extractor para transformar tus componentes y extraer el contenido

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npx intlayer extract
   

   Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

   Actualiza tu archivo vite.config.ts para incluir el plugin intlayerCompiler :

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { defineConfig } from "vite";
   import { intlayer, intlayerCompiler } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer(),
       intlayerCompiler(), // Adds the compiler plugin
     ],
   });
   

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm run build # O npm run dev
   

Configuración de TypeScript

Intlayer utiliza el aumento de módulos (module augmentation) para aprovechar TypeScript, haciendo que tu código sea más robusto.

Asegúrate de que tu configuración de TypeScript incluya los tipos autogenerados.

{
  // ... tu configuración de TypeScript existente
  "include": [
    // ... tu configuración de TypeScript existente
    ".intlayer/**/*.ts", // Incluir tipos autogenerados
  ],
}

Configuración de Git

Se recomienda ignorar los archivos generados por Intlayer. Esto evita incluirlos en tu repositorio de Git.

Para hacerlo, añade las siguientes instrucciones a tu archivo .gitignore:

# Ignorar archivos generados por Intlayer
.intlayer

Extensión de VS Code

Para mejorar tu experiencia de desarrollo con Intlayer, puedes instalar la extensión oficial de Intlayer para VS Code.

Instalar desde el VS Code Marketplace

Esta extensión proporciona:

• Autocompletado para las claves de traducción.
• Detección de errores en tiempo real para traducciones faltantes.
• Previsualización en línea del contenido traducido.
• Acciones rápidas para crear y actualizar traducciones fácilmente.

Para más información sobre el uso de la extensión, consulta la documentación de la extensión para VS Code.

Profundiza más

Si quieres saber más, también puedes implementar el Editor Visual o usar el CMS para externalizar tus contenidos.

Preguntas frecuentes