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

Tabla de Contenidos

¿Por qué Intlayer en lugar de alternativas?

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

Guía Paso a Paso para Configurar Intlayer en una Aplicación Vite y Svelte

Consulta la Plantilla de Aplicación en GitHub.

1. 1

   Instalar Dependencias

   Instala los paquetes necesarios usando npm:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

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

   • intlayer

     El paquete principal que proporciona herramientas de internacionalización para la gestión de configuración, traducción, declaración de contenido, transpileación y comandos CLI.

   • svelte-intlayer El paquete que integra Intlayer con la aplicación Svelte. Proporciona proveedores de contexto y hooks para la internacionalización en Svelte.

   • vite-intlayer Incluye el plugin de Vite para integrar Intlayer con el bundler Vite, así como middleware para detectar la configuración regional preferida del usuario, gestionar cookies y manejar redirecciones de URL.

2. 2

   Configuración de tu proyecto

   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 locales    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

   A través de este archivo de configuración, puedes configurar URLs localizadas, redirección mediante middleware, nombres de cookies, la ubicación y extensión de tus declaraciones de contenido, desactivar los logs 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. 3

   Integra Intlayer en tu configuración de Vite

   Agrega el plugin intlayer en tu configuración.

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [svelte(), intlayer()],});

   El plugin intlayer() para Vite se utiliza para integrar Intlayer con Vite. Asegura la construcción de los archivos de declaración de contenido y los supervisa en modo desarrollo. Define las variables de entorno de Intlayer dentro de la aplicación Vite. Además, proporciona alias para optimizar el rendimiento.

4. 4

   Declara tu contenido

   Crea y administra tus declaraciones de contenido para almacenar traducciones:

   src/app.content.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;

   Tus declaraciones de contenido pueden definirse en cualquier parte de tu aplicación tan pronto como se incluyan 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.

5. 5

   Utiliza Intlayer en tu código

   src/App.svelte

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   <script>  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("app");</script><div><!-- Renderizar contenido como contenido simple --><h1>{$content.title}</h1><!-- Para renderizar el contenido editable usando el editor --><h1>{@const Title = $content.title}<Title /></h1><!-- Para renderizar el contenido como una cadena --><div aria-label={$content.title.value}></div><div aria-label={$content.title.toString()}></div><div aria-label={String($content.title)}></div>

   Si su aplicación ya existe, puede utilizar el Compilador Intlayer, así como el comando de extracción, para transformar miles de componentes en un segundo.

6. 6

   Cambiar el idioma de tu contenido

   Opcional

   src/App.svelte

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   <script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from "svelte-intlayer";// Obtener información del locale y la función setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Manejar el cambio de localeconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  setLocale(newLocale);};</script><div>  <select value={$locale} on:change={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

7. 7

   Renderizar Markdown

   Opcional

   Intlayer soporta renderizar contenido Markdown directamente en tu aplicación Svelte. Por defecto, Markdown se trata como texto plano. Para convertir Markdown en HTML enriquecido, puedes integrar @humanspeak/svelte-markdown u otro parser de markdown.

   Para ver cómo declarar contenido markdown usando el paquete intlayer, consulta la documentación de markdown.

   src/App.svelte

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   <script>  import { setIntlayerMarkdown } from "svelte-intlayer";  setIntlayerMarkdown((markdown) =>   // renderizar el contenido markdown como una cadena   return markdown;  );</script><h1>{$content.markdownContent}</h1>

   También puedes acceder a los datos del front-matter de tu markdown usando la propiedad content.markdownContent.metadata.xxx.

8. 8

   Configurar el editor / CMS de intlayer

   Opcional

   Para configurar el editor de intlayer, debes seguir la documentación del editor de intlayer.

   Para configurar el CMS de intlayer, debes seguir la documentación del CMS de intlayer.

9. 7

   Añadir enrutamiento por localeizado a tu aplicación

   Opcional

   Para manejar el enrutamiento por localeizado en tu aplicación Svelte, puedes usar svelte-spa-router junto con localeFlatMap de Intlayer para generar rutas para cada locale.

   Primero, instala svelte-spa-router:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install svelte-spa-routernpx intlayer init

   Luego, crea un archivo Router.svelte para definir tus rutas:

   src/Router.svelte

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   <script lang="ts">import { localeFlatMap } from "intlayer";import Router from "svelte-spa-router";import { wrap } from "svelte-spa-router/wrap";import App from "./App.svelte";const routes = Object.fromEntries(    localeFlatMap(({locale, urlPrefix}) => [    [        urlPrefix || '/',        wrap({            component: App as any,            props: {                locale,            },        }),    ],    ]));</script><Router {routes} />

   Actualiza tu main.ts para montar el componente Router en lugar de App:

   src/main.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { mount } from "svelte";import Router from "./Router.svelte";const app = mount(Router, {  target: document.getElementById("app")!,});export default app;

   Finalmente, actualiza tu App.svelte para recibir la propiedad locale y usarla con useIntlayer:

   src/App.svelte

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   <script lang="ts">import type { Locale } from 'intlayer';import { useIntlayer } from "svelte-intlayer";import Counter from './lib/Counter.svelte';import LocaleSwitcher from './lib/LocaleSwitcher.svelte';export let locale: Locale;$: content = useIntlayer('app', locale);</script><main>  <div class="locale-switcher-container">    <LocaleSwitcher currentLocale={locale} />  </div>  <!-- ... resto de tu aplicación ... --></main>

   Configurar el enrutamiento del lado del servidor (Opcional)

   Paralelamente, también puedes usar intlayerProxy para añadir enrutamiento del lado del servidor a tu aplicación. Este plugin detectará automáticamente la locale actual basada en la URL y establecerá la cookie de locale correspondiente. Si no se especifica ninguna locale, el plugin determinará la locale más adecuada según las preferencias de idioma del navegador del usuario. Si no se detecta ninguna locale, redirigirá a la locale por defecto.

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

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { defineConfig } from "vite";
   import { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer, intlayerProxy } from "vite-intlayer";
   
     plugins: [intlayerProxy(), // should be placed first
    svelte(), intlayer()],
   });

10. 8

    Cambiar la URL cuando cambia la locale

    Opcional

    Para permitir que los usuarios cambien de idioma y actualicen la URL en consecuencia, puedes crear un componente LocaleSwitcher. Este componente usará getLocalizedUrl de intlayer y push de svelte-spa-router.

    src/lib/LocaleSwitcher.svelte

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    <script lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";import { push } from "svelte-spa-router";export let currentLocale: string | undefined = undefined;// Obtener información de la localeconst { locale, availableLocales } = useLocale();// Manejar el cambio de localeconst changeLocale = (event: Event) => {  plugins: [intlayerProxy(), // should be placed first svelte(), intlayer()],});

11. 8

    Cambiar la URL cuando cambia la configuración regional

    Opcional

    Para permitir que los usuarios cambien de idioma y actualicen la URL en consecuencia, puedes crear un componente LocaleSwitcher. Este componente utilizará getLocalizedUrl de intlayer y push de svelte-spa-router.

    src/lib/LocaleSwitcher.svelte

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    <script lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";import { push } from "svelte-spa-router";export let currentLocale: string | undefined = undefined;// Obtener información de la configuración regionalconst { locale, availableLocales } = useLocale();// Manejar el cambio de configuración regionalconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  const currentUrl = window.location.pathname;  const url = getLocalizedUrl( currentUrl, newLocale);  push(url);};</script><div class="locale-switcher">  <select value={currentLocale ?? $locale} onchange={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

12. 9

    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 se puede ejecutar solo una vez para transformar la aplicación y luego se puede eliminar.
         */
        saveComponents: false,
    
        /**
         * Prefijo de clave de diccionario
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;

    Comando de extracciónCompilador Babel

    Ejecuta el extractor para transformar tus componentes y extraer el contenido

    bash

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    npx intlayer extract

    Actualiza tu archivo vite.config.ts para incluir el plugin intlayerCompiler :

    vite.config.ts

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

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

    bash

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    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.

Configuración de Git

Se recomienda ignorar los archivos generados por Intlayer. Esto te permite evitar comprometerlos en tu repositorio Git.

Para hacerlo, puedes agregar las siguientes instrucciones a tu archivo .gitignore:

#  Ignorar los archivos generados por Intlayer.intlayer

Extensión para VS Code

Para mejorar tu experiencia de desarrollo con Intlayer, puedes instalar la extensión oficial Intlayer VS Code Extension.

Instalar desde el VS Code Marketplace

Esta extensión ofrece:

• Autocompletado para las 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 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.