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

Tabla de Contenidos

¿Qué es Intlayer?

Intlayer es una biblioteca de internacionalización (i18n) innovadora y de código abierto diseñada para simplificar el soporte multilingüe en aplicaciones web modernas.

Con Intlayer, puedes:

• Gestionar fácilmente las traducciones usando diccionarios declarativos a nivel de componente.
• Localizar dinámicamente metadatos, rutas y contenido.
• Asegurar el soporte de TypeScript con tipos autogenerados, mejorando el autocompletado y la detección de errores.
• Beneficiarte de funciones avanzadas, como la detección y el cambio dinámico de idioma.

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

Paso 1: Instalar dependencias

Instala los paquetes necesarios usando npm:

npm install intlayer vanilla-intlayernpm install vite-intlayer --save-devnpx intlayer init

• 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.

Paso 2: Configuración de tu proyecto

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

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.

Paso 3: Integrar Intlayer en tu configuración de Vite

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

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});

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.

Paso 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.

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:

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

Paso 5: Declara tu contenido

Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

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}).

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

Paso 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.

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 inicialdocument.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;

(Opcional) Paso 7: Cambiar el idioma de tu contenido

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

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));}

(Opcional) Paso 8: Renderizar contenido Markdown y HTML

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:

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));});

(Opcional) Paso 9: Añadir enrutamiento localizado a tu aplicación

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.

import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayerProxy(), // debe colocarse primero
    intlayer(),
  ],
});

(Opcional) Paso 10: Cambiar la URL cuando cambie el idioma

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

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();

(Opcional) Paso 11: Cambiar los atributos de idioma y dirección de HTML

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

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

(Opcional) Paso 12: Carga diferida de diccionarios por idioma

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:

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.

(Opcional) Paso 13: Extraer el contenido de tus componentes

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:

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;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Añade el plugin del compilador ],});

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.