Traduce tu Vite y Solid con Intlayer | Internacionalización (i18n)

Tabla de contenidos

Este paquete está en desarrollo. Consulta el issue para más información. Muestra tu interés en Intlayer para Solid dando like al issue

¿Por qué Intlayer en lugar de alternativas?

En comparación con soluciones principales como @solid-primitives/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 Solid

Tabla de contenidos

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 solid-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, transpilación y comandos CLI.

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

   • vite-intlayer Incluye el plugin de Vite para integrar Intlayer con el empaquetador Vite, así como middleware para detectar el idioma preferido 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 en middleware, nombres de cookies, la ubicación y extensión de tus declaraciones de contenido, deshabilitar 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. 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 react from "@vitejs/plugin-react-swc";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [react(), intlayer()],
   });

   El plugin intlayer() de Vite se utiliza para integrar Intlayer con Vite. Asegura la construcción de archivos de declaración de contenido y los supervisa 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

   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: {},
   } satisfies Dictionary;
   
   export default appContent;

   Tus declaraciones de contenido pueden definirse en cualquier lugar 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

   Accede a tus diccionarios de contenido en toda tu aplicación:

   src/App.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { createSignal, type Component } from "solid-js";import solidLogo from "./assets/solid.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "solid-intlayer";const AppContent: Component = () => {  const [count, setCount] = createSignal(0);  const content = useIntlayer("app");  return (    <>      <div>        <a href="https://vitejs.dev" target="_blank">          <img src={viteLogo} class="logo" alt={content.viteLogo.value} />        </a>        <a href="https://www.solidjs.com/" target="_blank">          <img            src={solidLogo}            class="logo solid"            alt={content.solidLogo.value}          />        </a>      </div>      <h1>{content.title}</h1>      <div class="card">        <button onClick={() => setCount((count) => count + 1)}>          {content.count({ count: count() })}        </button>        <p>{content.edit}</p>      </div>      <p class="read-the-docs">{content.readTheDocs}</p>    </>  );};const App: Component = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

   En Solid, useIntlayer devuelve una función accessor (por ejemplo, `content.). Debes llamar a esta función para acceder al contenido reactivo.

   Si quieres usar tu contenido en un atributo string, como alt, title, href, aria-label, etc., debes llamar al valor de la función, como:

   html

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

6. 6

   Cambia el idioma de tu contenido

   Opcional

   Para cambiar el idioma de tu contenido, puedes usar la función setLocale proporcionada por el hook useLocale. Esta función te permite establecer la configuración regional de la aplicación y actualizar el contenido en consecuencia.

   src/components/LocaleSwitcher.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { type Component, For } from "solid-js";import { Locales } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const { locale, setLocale, availableLocales } = useLocale();  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as Locales)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

7. 7

   Añade enrutamiento por localeizado a tu aplicación

   Opcional

   El propósito de este paso es crear rutas únicas para cada idioma. Esto es útil para SEO y URLs amigables para SEO. Ejemplo:

   plaintext

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   - https://example.com/about- https://example.com/es/about- https://example.com/fr/about

   Para añadir enrutamiento por localeizado a tu aplicación, puedes usar @solidjs/router.

   Primero, instala las dependencias necesarias:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install @solidjs/router

   Luego, envuelve tu aplicación con el Router y define tus rutas usando localeMap:

   src/index.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { render } from "solid-js/web";import { Router } from "@solidjs/router";import App from "./App";const root = document.getElementById("root");render(  () => (    <Router>      <App />    </Router>  ),  root!);

   src/App.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { type Component } from "solid-js";import { Route } from "@solidjs/router";import { localeMap } from "intlayer";import { IntlayerProvider } from "solid-intlayer";import Home from "./pages/Home";import About from "./pages/About";const App: Component = () => (  <IntlayerProvider>    {localeMap(({ locale, urlPrefix }) => (      <Route        path={urlPrefix || "/"}        component={(props: any) => (          <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>        )}      >        <Route path="/" component={Home} />        <Route path="/about" component={About} />      </Route>    ))}  </IntlayerProvider>);export default App;

8. 8

   Cambia la URL cuando cambie la configuración regional

   Opcional

   Para cambiar la URL cuando cambie la configuración regional, puedes usar la prop onLocaleChange proporcionada por el hook useLocale. Puedes usar los hooks useNavigate y useLocation de @solidjs/router para actualizar la ruta de la URL.

   src/components/LocaleSwitcher.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { type Component, For } from "solid-js";import { useLocation, useNavigate } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const location = useLocation();  const navigate = useNavigate();  const { locale, setLocale, availableLocales } = useLocale({    onLocaleChange: (loc) => {      const pathWithLocale = getLocalizedUrl(location.pathname, loc);      navigate(pathWithLocale);    },  });  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as any)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

9. 9

   Cambia los atributos de idioma y dirección en el 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.

   src/App.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { createEffect, type Component } from "solid-js";import { useLocale } from "solid-intlayer";import { getHTMLTextDir } from "intlayer";const AppContent: Component = () => {  const { locale } = useLocale();  createEffect(() => {    document.documentElement.lang = locale();    document.documentElement.dir = getHTMLTextDir(locale());  });  return (    // ... Tu contenido de aplicación  );};

10. 10

    Crear un Componente de Enlace Localizado

    Opcional

    Crea un componente Link personalizado que prefije automáticamente las URL internas con el idioma actual.

    src/components/Link.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { type ParentComponent } from "solid-js";import { A, type AnchorProps } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";export const Link: ParentComponent<AnchorProps> = (props) => {  const { locale } = useLocale();  const isExternal = () => props.href.startsWith("http");  const localizedHref = () =>    isExternal() ? props.href : getLocalizedUrl(props.href, locale());  return <A {...props} href={localizedHref()} />;};

11. 11

    Renderizar Markdown

    Opcional

    Intlayer admite renderizar contenido Markdown directamente en tu aplicación Solid usando su propio analizador interno. Por defecto, Markdown se trata como texto plano. Para renderizarlo como HTML enriquecido, envuelve tu aplicación con el MarkdownProvider.

    src/index.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { render } from "solid-js/web";import { MarkdownProvider } from "solid-intlayer/markdown";import App from "./App";const root = document.getElementById("root");render(  () => (    <MarkdownProvider>      <App />    </MarkdownProvider>  ),  root!);

    Luego puedes usarlo en tus componentes:

    tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { useIntlayer } from "solid-intlayer";const MyComponent = () => {  const content = useIntlayer("my-content");  return (    <div>      {/* Se renderiza como HTML a través de MarkdownProvider */}      {content.markdownContent}    </div>  );};

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

Configurar TypeScript

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

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

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

Esta extensión proporciona:

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