Traduce tu sitio web Vite y Vanilla JS usando Intlayer | Internacionalización (i18n)

Tabla de Contenidos

¿Por qué Intlayer en lugar de alternativas?

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

Guía paso a paso para configurar Intlayer en una aplicación Vite y Vanilla JS

1. 1

   Instalar dependencias

   Instala los paquetes necesarios usando npm:

   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 vanilla-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer El paquete principal que proporciona herramientas de internacionalización para la gestión de la configuración, traducción, declaración de contenido, transpilación y comandos de CLI.

   • vanilla-intlayer El paquete que integra Intlayer con aplicaciones de JavaScript puro / TypeScript. Proporciona un singleton pub/sub (IntlayerClient) y ayudantes basados en callbacks (useIntlayer, useLocale, etc.) para que cualquier parte de tu aplicación pueda reaccionar a los cambios de idioma sin depender de un framework de UI.

   • vite-intlayer Incluye el plugin de Vite para integrar Intlayer con el bundler Vite, así como middleware para detectar el idioma preferido del usuario, gestionar cookies y manejar la redirección de URL.

2. 2

   Configuración de tu proyecto

   Crea un archivo de configuración para configurar 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, redirección de middleware, nombres de cookies, la ubicación y extensión de tus declaraciones de contenido, desactivar los registros de Intlayer en la consola y más. Para obtener una lista completa de los parámetros disponibles, consulta la documentación de configuración.

3. 3

   Integrar Intlayer en tu configuración de Vite

   Añade el plugin de intlayer en tu configuración.

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

   El plugin de Vite intlayer() se utiliza para integrar Intlayer con Vite. Asegura la construcción de archivos de declaración de contenido y los monitorea en modo de desarrollo. Define variables de entorno de Intlayer dentro de la aplicación Vite. Además, proporciona alias para optimizar el rendimiento.

4. 4

   Inicializar Intlayer en tu punto de entrada

   Llama a installIntlayer() antes de que se renderice cualquier contenido para que el singleton de idioma global esté listo.

   src/main.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { installIntlayer } from "vanilla-intlayer";
   
   // Debe llamarse antes de renderizar cualquier contenido i18n.
   installIntlayer();
   
   // Importa y ejecuta tus módulos de aplicación.
   import "./app.js";
   

   Si también usas declaraciones de contenido md() (Markdown), instala también el renderizador de markdown:

   src/main.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";
   
   installIntlayer();
   installIntlayerMarkdown();
   
   import "./app.js";
   

5. 5

   Declara 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 { insert, t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "Vite + Vanilla",
   
       viteLogoLabel: t({
         en: "Vite Logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
   
       count: insert(
         t({
           en: "count is {{count}}",
           fr: "le compte est {{count}}",
           es: "el recuento es {{count}}",
         })
       ),
   
       readTheDocs: t({
         en: "Click on the Vite logo to learn more",
         fr: "Cliquez sur le logo Vite pour en savoir plus",
         es: "Haga clic en el logotipo de Vite para obtener más información",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

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

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

6. 6

   Usar Intlayer en tu JavaScript

   vanilla-intlayer refleja la API de superficie de react-intlayer: useIntlayer(key, locale?) devuelve el contenido traducido directamente. Encadena .onChange() en el resultado para suscribirte a los cambios de idioma - el equivalente explícito de un re-renderizado de React.

   src/main.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { installIntlayer, useIntlayer } from "vanilla-intlayer";
   
   installIntlayer();
   
   // Obtener el contenido inicial para el idioma actual.
   // Encadenar .onChange() para ser notificado cada vez que el idioma cambie.
   const content = useIntlayer("app").onChange((newContent) => {
     // Volver a renderizar o parchear solo los nodos DOM afectados
     document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(
       newContent.title
     );
     document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
       String(newContent.readTheDocs);
   });
   
   // Renderizado inicial
   document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(
     content.title
   );
   document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
     String(content.readTheDocs);
   

   Accede a los valores finales como cadenas envolviéndolos en String(), que llama al método toString() del nodo y devuelve el texto traducido.

   Cuando necesites el valor para un atributo HTML nativo (por ejemplo, alt, aria-label), utiliza .value directamente:

   typescript

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   img.alt = content.viteLogoLabel.value;
   

7. 7

   Cambiar el idioma de tu contenido

   Opcional

   Para cambiar el idioma de tu contenido, utiliza la función setLocale expuesta por useLocale.

   src/locale-switcher.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { getLocaleName } from "intlayer";
   import { useLocale } from "vanilla-intlayer";
   
   export function setupLocaleSwitcher(container: HTMLElement): () => void {
     const { locale, availableLocales, setLocale, subscribe } = useLocale();
   
     const select = document.createElement("select");
     select.setAttribute("aria-label", "Language");
   
     const render = (currentLocale: string) => {
       select.innerHTML = availableLocales
         .map(
           (loc) =>
             `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>
               ${getLocaleName(loc)}
             </option>`
         )
         .join("");
     };
   
     render(locale);
     container.appendChild(select);
   
     select.addEventListener("change", () => setLocale(select.value as any));
   
     // Mantener el menú desplegable sincronizado cuando el idioma cambie desde otro lugar
     return subscribe((newLocale) => render(newLocale));
   }
   

8. 8

   Renderizar contenido Markdown y HTML

   Opcional

   Intlayer admite declaraciones de contenido md() y html(). En vanilla JS, la salida compilada se inserta como HTML puro a través de innerHTML.

   Compila e inyecta el HTML:

   src/main.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import {
     compileMarkdown,
     installIntlayerMarkdown,
     useIntlayer,
   } from "vanilla-intlayer";
   
   installIntlayerMarkdown();
   
   const content = useIntlayer("app").onChange((newContent) => {
     const el = document.querySelector<HTMLDivElement>(".edit-note")!;
     el.innerHTML = compileMarkdown(String(newContent.editNote));
   });
   
   document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
     compileMarkdown(String(content.editNote));
   

   TIP

   String(content.editNote) llama a toString() en el IntlayerNode, que devuelve la cadena Markdown pura. Pásala a compileMarkdown para obtener una cadena HTML, luego configúrala a través de innerHTML.

   WARNING

   Solo usa innerHTML con contenido de confianza. Si el markdown proviene de la entrada del usuario, desinféctalo primero (por ejemplo, con DOMPurify). Puedes instalar un renderizador de desinfección dinámicamente:

   typescript

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";
   
   await installIntlayerMarkdownDynamic(async () => {
     const DOMPurify = await import("dompurify");
     return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));
   });
   

9. 9

   Añadir enrutamiento por localeizado a tu aplicación

   Opcional

   Para crear rutas únicas para cada idioma (útil para el SEO), puedes usar intlayerProxy en tu configuración de Vite para la detección del idioma en el lado del servidor.

   Primero, añade intlayerProxy a tu configuración de Vite:

   Ten en cuenta que para usar intlayerProxy en producción, necesitas mover vite-intlayer de devDependencies a dependencies.

   Desde Intlayer v9, intlayerProxy() está agrupado directamente en el plugin intlayer() y habilitado por defecto a través de la opción routing.enableProxy (true por defecto). Registrarlo por separado como se muestra a continuación es ahora opcional — se mantiene para compatibilidad hacia atrás y para configuraciones que necesitan controlar el orden de los plugins. Establece routing.enableProxy: false para optar por no participar. Consulta las notas de la versión v9.

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

10. 10

    Cambiar la URL cuando cambie el idioma

    Opcional

    Para actualizar la URL del navegador cuando cambie el idioma, llama a useRewriteURL() después de instalar Intlayer:

    src/main.ts

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { installIntlayer, useRewriteURL } from "vanilla-intlayer";
    
    installIntlayer();
    
    // Sobrescribe la URL inmediatamente y en cada cambio de idioma posterior.
    // Devuelve una función de cancelación de suscripción para la limpieza.
    const stopRewriteURL = useRewriteURL();
    

11. 11

    Cambiar los atributos de idioma y dirección de HTML

    Opcional

    Actualiza los atributos lang y dir de la etiqueta <html> para que coincidan con el idioma actual para la accesibilidad y el SEO.

    src/main.ts

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { getHTMLTextDir } from "intlayer";
    import { installIntlayer, useLocale } from "vanilla-intlayer";
    
    installIntlayer();
    
    useLocale({
      onLocaleChange: (locale) => {
        document.documentElement.lang = locale;
        document.documentElement.dir = getHTMLTextDir(locale);
      },
    });
    

12. 12

    Carga diferida de diccionarios por idioma

    Opcional

    Para aplicaciones grandes, es posible que desees dividir el diccionario de cada idioma en su propio fragmento. Usa useDictionaryDynamic junto con el import() dinámico de Vite:

    src/app.ts

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";
    
    installIntlayer();
    
    const unsubscribe = useDictionaryDynamic(
      {
        en: () => import("../.intlayer/dictionaries/en/app.mjs"),
        fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),
        es: () => import("../.intlayer/dictionaries/es/app.mjs"),
      },
      "app"
    ).onChange((content) => {
      document.querySelector("h1")!.textContent = String(content.title);
    });
    

    El paquete de cada idioma se recupera solo cuando ese idioma se activa y el resultado se almacena en caché; los cambios posteriores al mismo idioma son instantáneos.

13. 13

    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 añadir 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 config
      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 puede ejecutarse solo una vez para transformar la aplicación y luego puede eliminarse.
         */
        saveComponents: false,
    
        /**
         * Prefijo de clave de diccionario
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Comando ExtractCompilador 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 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
    

(Opcional) Sitemap y robots.txt (generación en el build)

Intlayer ofrece utilidades - generateSitemap y getMultilingualUrls - para formatear un sitemap.xml multilingüe y un robots.txt listos para rastreadores y escribirlos automáticamente en public/. Lo habitual es ejecutar un script pequeño de Node antes de Vite (por ejemplo hooks npm predev / prebuild) para que esos archivos existan al compilar o al levantar el servidor de desarrollo.

Sitemap

El generador de sitemaps de Intlayer respeta tu configuración de idiomas y añade los metadatos habituales.

El sitemap admite el espacio de nombres xhtml:link (hreflang). En lugar de listar solo URLs sueltas, Intlayer enlaza de forma bidireccional todas las versiones localizadas de cada página (p. ej. /about, /fr/about o /about?lang=fr según el modo de rutas).

Robots.txt

Usa getMultilingualUrls para que las reglas Disallow cubran todas las variantes localizadas de rutas sensibles.

1. Crear generate-seo.mjs en la raíz del proyecto

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

Debe estar instalado intlayer para poder importarlo. Define SITE_URL en el entorno en producción (por ejemplo en CI).

Prefiere generate-seo.mjs para ESM en Node. Si usas generate-seo.js, asegúrate de tener "type": "module" en package.json o ejecuta Node con ESM.

2. Ejecutar el script antes de Vite

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Ajusta los comandos si usas pnpm o yarn. También puedes llamar al script desde CI u otro paso del pipeline.

Configurar TypeScript

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

{
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

Configuración de Git

Se recomienda ignorar los archivos generados por Intlayer. Esto te permite evitar enviarlos a tu repositorio de Git.

Para hacer esto, puedes añadir las siguientes instrucciones a tu archivo .gitignore:

# Ignorar los 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 claves de traducción.
• Detección de errores en tiempo real para traducciones faltantes.
• Vistas previas en línea del contenido traducido.
• Acciones rápidas para crear y actualizar traducciones fácilmente.

Para obtener más detalles sobre cómo usar la extensión, consulta la documentación de la Extensión de Intlayer para VS Code.

Ir más allá

Para ir más allá, puedes implementar el editor visual o externalizar tu contenido usando el CMS.

Preguntas frecuentes