@intlayer/docs 8.4.10 → 8.5.1

package/docs/es/intlayer_with_vite+lit.md

@@ -0,0 +1,698 @@
+---
+createdAt: 2026-03-23
+updatedAt: 2026-03-23
+title: i18n Vite + Lit - Cómo traducir una aplicación Lit en 2026
+description: Descubre cómo hacer que tu sitio web Vite y Lit sea multilingüe. Sigue la documentación para internacionalizarlo (i18n) y traducirlo.
+keywords:
+  - Internacionalización
+  - Documentación
+  - Intlayer
+  - Vite
+  - Lit
+  - Web Components
+  - JavaScript
+slugs:
+  - doc
+  - environment
+  - vite-and-lit
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-lit-template
+history:
+  - version: 8.4.10
+    date: 2026-03-23
+    changes: "Init history"
+---
+
+# Traduce tu sitio web Vite y Lit usando Intlayer | Internacionalización (i18n)
+
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer-vite-lit-template?embed=1&ctl=1&file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+## Tabla de Contenidos
+
+<TOC/>
+
+## ¿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:
+
+```bash packageManager="npm"
+npm install intlayer lit-intlayer
+npm install vite-intlayer --save-dev
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer lit-intlayer
+pnpm add vite-intlayer --save-dev
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer lit-intlayer
+yarn add vite-intlayer --save-dev
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer lit-intlayer
+bun add vite-intlayer --dev
+bunx 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/content_file.md), transpilación y [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/index.md).
+
+- **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](https://vite.dev/guide/why.html#why-bundle-for-production), 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:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+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;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Tus otros idiomas
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Tus otros idiomas
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md).
+
+### Paso 3: Integrar Intlayer en tu configuración de Vite
+
+Agrega el complemento intlayer en tu configuración.
+
+```typescript fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+```javascript fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+```javascript fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const { intlayer } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = 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.
+
+```typescript fileName="src/main.ts" codeFormat="typescript"
+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:
+
+```typescript fileName="src/main.ts" codeFormat="typescript"
+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:
+
+```typescript fileName="src/app.content.ts" contentDeclarationFormat="typescript"
+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;
+```
+
+```javascript fileName="src/app.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+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",
+    }),
+  },
+};
+
+export default appContent;
+```
+
+```javascript fileName="src/app.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+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 para obtener más información",
+      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
+    }),
+  },
+};
+
+module.exports = appContent;
+```
+
+```json fileName="src/app.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "app",
+  "content": {
+    "title": "Vite + Lit",
+    "viteLogo": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Vite logo",
+        "fr": "Logo Vite",
+        "es": "Logo Vite"
+      }
+    },
+    "litLogo": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Lit logo",
+        "fr": "Logo Lit",
+        "es": "Logo Lit"
+      }
+    },
+    "count": {
+      "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 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"
+      }
+    }
+  }
+}
+```
+
+> 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/content_file.md).
+
+### 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.
+
+```typescript fileName="src/my-element.ts" codeFormat="typescript"
+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>
+    `;
+  }
+}
+```
+
+> [!NOTE]
+> Cuando necesites la cadena traducida en un atributo HTML nativo (por ejemplo, `alt`, `aria-label`, `title`), llama a `.value` en el nodo hoja:
+>
+> ```typescript
+> html`<img alt=${content.viteLogo.value} />`;
+> ```
+
+### (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`.
+
+```typescript fileName="src/locale-switcher.ts" codeFormat="typescript"
+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`.
+
+```typescript fileName="src/app.content.ts" contentDeclarationFormat="typescript"
+import { md, t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    // ...
+    editNote: md(
+      t({
+        en: "Edit `src/my-element.ts` and save to test **HMR**",
+        fr: "Modifiez `src/my-element.ts` et enregistrez pour tester **HMR**",
+        es: "Edite `src/my-element.ts` y guarde para probar **HMR**",
+      })
+    ),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+Renderiza el HTML compilado en tu elemento:
+
+```typescript fileName="src/my-element.ts" codeFormat="typescript"
+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`.
+
+```typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import { intlayer, intlayerProxy } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayerProxy(), // should be placed first
+    intlayer(),
+  ],
+});
+```
+
+```javascript {3,7} fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import { intlayer, intlayerProxy } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayerProxy(), // should be placed first
+    intlayer(),
+  ],
+});
+```
+
+```javascript {3,7} fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const { intlayer, intlayerProxy } = require("vite-intlayer");
+
+module.exports = 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:
+
+```typescript fileName="src/locale-switcher.ts" codeFormat="typescript"
+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.
+
+```typescript fileName="src/my-element.ts" codeFormat="typescript"
+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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/extract.md) para transformar tus componentes y extraer el contenido.
+
+Para configurarlo, puedes agregar una sección `compiler` en tu archivo `intlayer.config.ts`:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+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;
+```
+
+### Configurar TypeScript
+
+Asegúrate de que tu configuración de TypeScript incluya los tipos autogenerados.
+
+```json5 fileName="tsconfig.json"
+{
+  "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`:
+
+```bash
+# 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](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+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](https://intlayer.org/doc/vs-code-extension).
+
+---
+
+### Ir más lejos
+
+Para ir más lejos, puedes implementar el [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md) o externalizar tu contenido usando el [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md).