Creación:2026-03-31Última actualización:2026-05-31

    Traduce tu sitio web 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:

    Intlayer está optimizado para funcionar perfectamente con Vanilla JavaScript al ofrecer administración de contenido independiente del marco, compatibilidad con TypeScript y todas las funciones necesarias para escalar la internacionalización (i18n).

    En lugar de cargar archivos JSON masivos en sus páginas, cargue solo el contenido necesario. Intlayer ayuda a reducir el tamaño de su bundle y de sus páginas hasta en un 50%.

    Determinar el alcance del contenido de su aplicación facilita el mantenimiento para aplicaciones a gran escala. Puede duplicar o eliminar una sola carpeta de funciones sin la carga mental de revisar todo el código base de contenido. Además, Intlayer está completamente escrito para garantizar la precisión de su contenido.

    La ubicación conjunta de contenido reduce el contexto necesario para los modelos de lenguajes grandes (LLM). Intlayer también viene con un conjunto de herramientas, como una CLI para comprobar si faltan traducciones,LSP, MCP y agent skills, para que la experiencia del desarrollador (DX) sea aún más fluida para los agentes de IA.

    Utilice la automatización para traducir su canal de CI/CD utilizando el LLM de su elección al costo de su proveedor de IA. Intlayer también ofrece un compilador para automatizar la extracción de contenido, así como una plataforma web para ayudar a traducir en segundo plano.

    La conexión de archivos JSON masivos a componentes puede provocar problemas de rendimiento y reactividad. Intlayer optimiza la carga de su contenido en el momento de la compilación.

    Más que una simple solución i18n, Intlayer proporciona un [editor visual] autohospedado(/es/doc/concept/editor) y un CMS completo para ayudarle a administrar su contenido multilingüe en tiempo real, lo que facilita la colaboración con traductores, redactores y otros miembros del equipo. El contenido se puede almacenar de forma local y/o remota.

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

    1. Instalar dependencias

      Instala los paquetes necesarios usando npm:

      # Generar un paquete independiente de intlayer y vanilla-intlayer
# Este archivo se importará en tu archivo HTML
npx intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inicializar intlayer con el archivo de configuración
npx intlayer init --no-gitignore

# Construir los diccionarios
npx intlayer build
      # Generar un paquete independiente de intlayer y vanilla-intlayer
# Este archivo se importará en tu archivo HTML
pnpm intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inicializar intlayer con el archivo de configuración
pnpm intlayer init --no-gitignore

# Construir los diccionarios
pnpm intlayer build
      # Generar un paquete independiente de intlayer y vanilla-intlayer
# Este archivo se importará en tu archivo HTML
yarn intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inicializar el archivo de configuración de intlayer, TypeScript si está configurado, variables de entorno
yarn intlayer init --no-gitignore

# Construir los diccionarios
yarn intlayer build
      # Generar un paquete independiente de intlayer y vanilla-intlayer
# Este archivo se importará en tu archivo HTML
bun x intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inicializar intlayer con el archivo de configuración
bun x intlayer init --no-gitignore

# Construir los diccionarios
bun x intlayer build

      • 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 puras de JavaScript / TypeScript. Proporciona un singleton de publicación/suscripción (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.

      La exportación de empaquetado (bundling) del CLI intlayer standalone produce una compilación optimizada mediante la eliminación de código muerto (tree-shaking) de paquetes no utilizados, idiomas y lógica no esencial (como redireccionamientos o prefijos) específica de su configuración.

    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 una lista completa de los parámetros disponibles, consulta la documentación de configuración.

    3. Importar el paquete en tu HTML

      Una vez que hayas generado el paquete intlayer.js, puedes importarlo en tu archivo HTML:

      <!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />

    <!-- Importar el paquete -->
    <script src="./intlayer.js" defer></script>
    <!-- Importar tu script principal -->
    <script src="./src/main.js" defer></script>
  </head>
  <body>
    <h1 id="title"></h1>
    <p class="read-the-docs"></p>
  </body>
</html>

      El paquete expone Intlayer y VanillaIntlayer como objetos globales en window.

    4. Inicializar Intlayer en tu punto de entrada

      En tu src/main.js, llama a installIntlayer() antes de que se renderice cualquier contenido para que el singleton global de idioma esté listo.

      const { installIntlayer } = window.VanillaIntlayer;

// Debe llamarse antes de renderizar cualquier contenido i18n.
installIntlayer();

      Si también quieres usar el renderizador de markdown, llama a installIntlayerMarkdown():

      const { installIntlayer, installIntlayerMarkdown } = window.VanillaIntlayer;

installIntlayer();
installIntlayerMarkdown();

    5. Declarar 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;
      {
  "$schema": "https://intlayer.org/schema.json",
  "key": "app",
  "content": {
    "title": "Vite + Vanilla",
    "viteLogoLabel": {
      "nodeType": "translation",
      "translation": {
        "en": "Vite Logo",
        "fr": "Logo Vite",
        "es": "Logo Vite"
      }
    },
    "count": {
      "nodeType": "insertion",
      "insertion": {
        "nodeType": "translation",
        "translation": {
          "en": "count is {{count}}",
          "fr": "le compte est {{count}}",
          "es": "el recuento es {{count}}"
        }
      }
    },
    "readTheDocs": {
      "nodeType": "translation",
      "translation": {
        "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"
      }
    }
  }
}

      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 coincidan con la extensión de archivo de declaración de contenido (por defecto, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

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

    6. Usar Intlayer en tu JavaScript

      El objeto window.VanillaIntlayer proporciona ayudantes de API: useIntlayer(key, locale?) devuelve el contenido traducido para una clave dada.

      const { installIntlayer, useIntlayer } = window.VanillaIntlayer;

installIntlayer();

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

// Renderizado inicial
document.querySelector("h1").textContent = String(content.title);
document.querySelector(".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), usa .value directamente:

      img.alt = content.viteLogoLabel.value;

    7. Cambiar el idioma de tu contenido

      Opcional

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

      const { getLocaleName } = window.Intlayer;
const { useLocale } = window.VanillaIntlayer;

export function setupLocaleSwitcher(container) {
  const { locale, availableLocales, setLocale, subscribe } = useLocale();

  const select = document.createElement("select");
  select.setAttribute("aria-label", "Idioma");

  const render = (currentLocale) => {
    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));

  // Mantener el menú desplegable sincronizado cuando el idioma cambia desde otro lugar
  return subscribe((newLocale) => render(newLocale));
}

    8. Cambiar los atributos de idioma y dirección HTML

      Opcional

      Actualiza los atributos lang y dir de la etiqueta <html> para que coincidan con la configuración regional actual para accesibilidad y SEO.

      const { getHTMLTextDir } = window.Intlayer;
const { installIntlayer, useLocale } = window.VanillaIntlayer;

installIntlayer();

useLocale({
  onLocaleChange: (locale) => {
    document.documentElement.lang = locale;
    document.documentElement.dir = getHTMLTextDir(locale);
  },
});

    9. Carga diferida de diccionarios por idioma

      Opcional

      Si deseas cargar diferidamente diccionarios por idioma, puedes usar useDictionaryDynamic. Esto es útil si no deseas incluir todas las traducciones en el archivo inicial intlayer.js.

      const { installIntlayer, useDictionaryDynamic } = window.VanillaIntlayer;

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

      Nota: useDictionaryDynamic requiere que los diccionarios estén disponibles como archivos ESM separados. Este enfoque se usa típicamente si tienes un servidor web que sirve los diccionarios.

    Configurar TypeScript

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

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

    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 Market de VS Code

    Esta extensión proporciona:

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

    Para más detalles sobre cómo usar la extensión, consulta la documentación de la extensión 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.

    ¿Por qué Intlayer?