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

Tabla de Contenidos

¿Qué es Intlayer?

Intlayer es una innovadora biblioteca de internacionalización (i18n) 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 Lit

Paso 1: Instalar dependencias

Instala los paquetes necesarios usando npm:

npm install intlayer lit-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 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.

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

Agrega el complemento intlayer en tu configuración.

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

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

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.

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

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:

import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";

Paso 5: Declarar tu contenido

Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

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

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

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

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

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

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

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

(Opcional) Paso 8: Renderizar contenido Markdown y HTML

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:

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.

(Opcional) Paso 9: Agregar enrutamiento localizado a tu aplicación

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.

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

export default defineConfig({
  plugins: [
    intlayerProxy(), // should be placed first
    intlayer(),
  ],
});

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

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

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

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

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

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

(Opcional) Paso 12: 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 agregar una sección compiler en tu archivo intlayer.config.ts:

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.