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

Tabla de Contenidos

¿Por qué Intlayer en lugar de alternativas?

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

Ver Application Template en GitHub.

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

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 lit-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 CLI.

   • lit-intlayer El paquete que integra Intlayer con aplicaciones Lit. Proporciona ganchos (hooks) basados en ReactiveController (useIntlayer, useLocale, etc.) para que los LitElements se vuelvan a renderizar automáticamente cuando cambia el idioma.

   • vite-intlayer Incluye el complemento Vite para integrar Intlayer con el empaquetador 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

   Arquitectura

   En esta arquitectura, lit-intlayer proporciona integraciones de elementos personalizados y controladores reactivos para gestionar traducciones dentro de Web Components. Las declaraciones de contenido se ubican en src/ junto a los elementos.

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   .
   ├── src
   │   ├── app.content.ts
   │   ├── index.css
   │   ├── locale-switcher.ts
   │   ├── main.ts
   │   └── my-element.ts                 # Main Lit element
   ├── index.html
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

   Configuración

   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

   Agrega el complemento 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 complemento 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 registren los elementos personalizados para que el singleton de idioma global esté listo cuando se conecte el primer elemento.

   src/main.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { installIntlayer } from "lit-intlayer";
   
   // Debe llamarse antes de que cualquier LitElement se conecte al DOM.
   installIntlayer();
   
   // Importa y registra tus elementos personalizados.
   import "./my-element.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 "lit-intlayer";
   
   installIntlayer();
   installIntlayerMarkdown();
   
   import "./my-element.js";
   

5. 5

   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: {
       title: "Vite + Lit",
   
       viteLogo: t({
         en: "Vite logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
       litLogo: t({
         en: "Lit logo",
         fr: "Logo Lit",
         es: "Logo Lit",
       }),
   
       count: t({
         en: "count is {{count}}",
         fr: "le compte est {{count}}",
         es: "el recuento es {{count}}",
       }),
   
       readTheDocs: t({
         en: "Click on the Vite and Lit logos to learn more",
         fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
         es: "Haga clic en los logotipos de Vite y Lit 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 coincidan 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 más detalles, consulta la documentación de declaración de contenido.

6. 6

   Utilizar Intlayer en tu LitElement

   Usa useIntlayer dentro de un LitElement. Devuelve un proxy ReactiveController que activa automáticamente los re-renderizados cada vez que cambia el idioma activo, sin necesidad de configuración adicional.

   src/my-element.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { LitElement, html } from "lit";
   import { customElement, property } from "lit/decorators.js";
   import { useIntlayer } from "lit-intlayer";
   
   @customElement("my-element")
   export class MyElement extends LitElement {
     @property({ type: Number })
     count = 0;
   
     // useIntlayer se registra como un ReactiveController.
     // El elemento se vuelve a renderizar automáticamente cuando cambia el idioma.
     private content = useIntlayer(this, "app");
   
     override render() {
       const { content } = this;
   
       return html`
         <h1>${content.title}</h1>
   
         <img src="/vite.svg" alt=${content.viteLogo.value} />
         <img src="/lit.svg" alt=${content.litLogo.value} />
   
         <button @click=${() => this.count++}>
           ${content.count({ count: this.count })}
         </button>
   
         <p>${content.readTheDocs}</p>
       `;
     }
   }
   

   Cuando necesites la cadena traducida en un atributo HTML nativo (por ejemplo, alt, aria-label, title), llama a .value en el nodo hoja:

   typescript

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   html`<img alt=${content.viteLogo.value} />`;
   html`<img alt=${content.viteLogo.toString()} />`;
   html`<img alt=${String(content.viteLogo)} />`;
   

7. 7

   Cambiar el idioma de tu contenido

   Opcional

   Para cambiar el idioma de tu contenido, usa el método setLocale expuesto por el controlador useLocale.

   src/locale-switcher.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { LitElement, html } from "lit";
   import { customElement } from "lit/decorators.js";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "lit-intlayer";
   
   @customElement("locale-switcher")
   export class LocaleSwitcher extends LitElement {
     private locale = useLocale(this);
   
     private _onChange(e: Event) {
       const select = e.target as HTMLSelectElement;
       this.locale.setLocale(select.value as any);
     }
   
     override render() {
       return html`
         <select @change=${this._onChange}>
           ${this.locale.availableLocales.map(
             (loc) => html`
               <option value=${loc} ?selected=${loc === this.locale.locale}>
                 ${getLocaleName(loc)}
               </option>
             `
           )}
         </select>
       `;
     }
   }
   

8. 8

   Renderizar contenido Markdown y HTML

   Opcional

   Intlayer admite declaraciones de contenido md() y html(). En Lit, la salida compilada se inyecta como HTML sin procesar a través de la directiva unsafeHTML.

   Renderiza el HTML compilado en tu elemento:

   src/my-element.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { LitElement, html } from "lit";
   import { customElement } from "lit/decorators.js";
   import { unsafeHTML } from "lit/directives/unsafe-html.js";
   import { useIntlayer } from "lit-intlayer";
   import { compileMarkdown } from "lit-intlayer/markdown";
   
   @customElement("my-element")
   export class MyElement extends LitElement {
     private content = useIntlayer(this, "app");
   
     override render() {
       return html`
         <div class="edit-note">
           ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}
         </div>
       `;
     }
   }
   

   TIP

   String(content.editNote) llama a toString() en el IntlayerNode, que devuelve la cadena Markdown sin procesar. Pásala a compileMarkdown para obtener una cadena HTML, luego renderízala con la directiva unsafeHTML de Lit.

9. 9

   Agregar enrutamiento por localeizado a tu aplicación

   Opcional

   Para crear rutas únicas para cada idioma (útil para SEO), puedes usar un enrutador del lado del cliente junto con los ayudantes localeMap / localeFlatMap de Intlayer, y el complemento Vite intlayerProxy para la detección de idioma del lado del servidor.

   Primero, agrega intlayerProxy a tu configuración de Vite:

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

   Desde Intlayer v9, intlayerProxy() está incluido 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 cambia el idioma

    Opcional

    Para actualizar la URL del navegador cuando cambia el idioma, usa useRewriteURL junto con el selector de idioma:

    src/locale-switcher.ts

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { LitElement, html } from "lit";
    import { customElement } from "lit/decorators.js";
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale, useRewriteURL } from "lit-intlayer";
    
    @customElement("locale-switcher")
    export class LocaleSwitcher extends LitElement {
      private locale = useLocale(this);
    
      // Reescribe automáticamente la URL actual cuando cambia el idioma.
      private _rewriteURL = useRewriteURL(this);
    
      private _onChange(e: Event) {
        const select = e.target as HTMLSelectElement;
        this.locale.setLocale(select.value as any);
      }
    
      override render() {
        return html`
          <select @change=${this._onChange}>
            ${this.locale.availableLocales.map(
              (loc) => html`
                <option value=${loc} ?selected=${loc === this.locale.locale}>
                  ${getLocaleName(loc)}
                </option>
              `
            )}
          </select>
        `;
      }
    }
    

11. 11

    Cambiar los atributos de idioma y dirección HTML

    Opcional

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

    src/my-element.ts

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { LitElement, html } from "lit";
    import { customElement } from "lit/decorators.js";
    import { getHTMLTextDir } from "intlayer";
    import { useLocale } from "lit-intlayer";
    
    @customElement("my-element")
    export class MyElement extends LitElement {
      private locale = useLocale(this, {
        onLocaleChange: (loc) => {
          document.documentElement.lang = loc;
          document.documentElement.dir = getHTMLTextDir(loc);
        },
      });
    
      override render() {
        return html`<!-- tu contenido -->`;
      }
    }
    

12. 12

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

(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": {
    // ...
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

experimentalDecorators y useDefineForClassFields: false son requeridos por Lit para el soporte de decoradores.

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 agregar 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 lejos

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

Preguntas frecuentes