Traduce tu sitio web de React Router v7 usando Intlayer | Internacionalización (i18n)

Esta guía demuestra cómo integrar Intlayer para internacionalización sin interrupciones en proyectos de React Router v7 con enrutamiento consciente de la configuración regional, soporte de TypeScript y prácticas modernas de desarrollo.

Cubre tanto enrutamiento basado en configuración (routes.ts) como enrutamiento basado en sistema de archivos (@react-router/fs-routes).

Tabla de contenidos

¿Por qué Intlayer sobre alternativas?

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

Guía paso a paso para configurar Intlayer en una aplicación React Router v7

VideoCode (Config-based)Code (File-System Routes)Demo (Config-based)

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-react-router-v7.vercel.app

Open embedded page in fullscreen

Consulta la plantilla de enrutamiento basado en configuración o la plantilla de rutas del sistema de archivos en GitHub.

1. 1

   Instalar dependencias

   Instala los paquetes necesarios usando tu gestor de paquetes preferido:

   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á tu entorno e instalará los paquetes requeridos. Por ejemplo:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install intlayer react-intlayer
   npm install vite-intlayer --save-dev
   

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

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

   • 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 { type IntlayerConfig, Locales } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       defaultLocale: Locales.ENGLISH,
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     },
   };
   
   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, deshabilitar logs de Intlayer en la consola, y más. Para una lista completa de parámetros disponibles, consulta la documentación de configuración.

3. 3

   Integrar Intlayer en tu configuración de Vite

   Añade el plugin intlayer a tu configuración:

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { reactRouter } from "@react-router/dev/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [reactRouter(), intlayer()],
   });
   

   El plugin 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

   Configurar rutas de React Router v7

   Enrutamiento basado en configuraciónRutas del sistema de archivos

   Configura tu configuración de enrutamiento con rutas que tengan en cuenta la configuración regional:

   app/routes.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { layout, route, type RouteConfig } from "@react-router/dev/routes";
   
   export default [
     route("/:locale?", "routes/page.tsx"), // Página de inicio localizada
     route("/:locale?/about", "routes/about/page.tsx"), // Página acerca de localizada
   ] satisfies RouteConfig;
   

   Configura tu configuración de enrutamiento para usar rutas basadas en el sistema de archivos con flatRoutes:

   app/routes.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { RouteConfig } from "@react-router/dev/routes";
   import { flatRoutes } from "@react-router/fs-routes";
   import { configuration } from "intlayer";
   
   const routes: RouteConfig = flatRoutes({
     // Ignora los archivos de declaración de contenido para que no se traten como rutas
     ignoredRouteFiles: configuration.content.fileExtensions.map(
       (fileExtension) => `**/*${fileExtension}`
     ),
   });
   
   export default routes;
   

   La función flatRoutes de @react-router/fs-routes habilita el enrutamiento basado en el sistema de archivos, donde la estructura de archivos en el directorio routes/ determina las rutas de tu aplicación. La opción ignoredRouteFiles asegura que los archivos de declaración de contenido de Intlayer (.content.ts, etc.) no se traten como archivos de ruta.

5. 5

   Crear componentes de diseño

   Configura tu diseño raíz y diseños específicos de la configuración regional:

   Layout raíz

   app/root.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { getLocaleFromPath } from "intlayer";
   import { IntlayerProvider } from "react-intlayer";
   import {
     data,
     Meta,
     Scripts,
     ScrollRestoration,
     useLoaderData,
   } from "react-router";
   import type { Route } from "./+types/root";
   
   // ... Código de App, links y ErrorBoundary sin cambios
   
   export async function loader({ request }: Route.LoaderArgs) {
     const locale = getLocaleFromPath(request.url);
   
     if (!locale) {
       throw data("Language not supported", { status: 404 });
     }
   
     return { locale };
   }
   
   export function Layout({
     children,
   }: { children: React.ReactNode } & Route.ComponentProps) {
     const data = useLoaderData<typeof loader>();
     const { locale } = data ?? {};
   
     return (
       <html lang={locale}>
         <head>
           <meta charSet="utf-8" />
           <meta content="width=device-width, initial-scale=1" name="viewport" />
           <Meta />
           <Links />
         </head>
         <body>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
           <ScrollRestoration />
           <Scripts />
         </body>
       </html>
     );
   }
   

6. 6

   Declare Your Content

   Cree y administre sus declaraciones de contenido para almacenar traducciones:

   app/routes/page.content.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { t, type Dictionary } from "intlayer";
   
   const pageContent = {
     key: "page",
     content: {
       title: t({
         es: "Bienvenido a React Router v7 + Intlayer",
         en: "Welcome to React Router v7 + Intlayer",
         fr: "Bienvenue sur React Router v7 + Intlayer",
       }),
       description: t({
         es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",
         en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
         fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",
       }),
       aboutLink: t({
         es: "Aprender Sobre Nosotros",
         en: "Learn About Us",
         fr: "En savoir plus sur nous",
       }),
       homeLink: t({
         es: "Inicio",
         en: "Home",
         fr: "Accueil",
       }),
     },
   } satisfies Dictionary;
   
   export default pageContent;
   

   Sus declaraciones de contenido pueden definirse en cualquier parte de su aplicación siempre que se incluyan en el directorio contentDir (por defecto, ./app). Y que 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}).

   Podría colocarse en app/routes/($locale)._index.content.ts en caso de usar enrutamiento basado en el sistema de archivos.

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

7. 7

   Create Locale-Aware Components

   Cree un componente LocalizedLink para navegación con conocimiento de locale:

   app/components/localized-link.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { FC } from "react";
   
   import { getLocalizedUrl, type LocalesValues } from "intlayer";
   import { useLocale } from "react-intlayer";
   import { Link, type LinkProps, type To } from "react-router";
   
   const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);
   
   export const locacalizeTo = (to: To, locale: LocalesValues): To => {
     if (typeof to === "string") {
       if (isExternalLink(to)) {
         return to;
       }
   
       return getLocalizedUrl(to, locale);
     }
   
     if (isExternalLink(to.pathname ?? "")) {
       return to;
     }
   
     return {
       ...to,
       pathname: getLocalizedUrl(to.pathname ?? "", locale),
     };
   };
   
   export const LocalizedLink: FC<LinkProps> = (props) => {
     const { locale } = useLocale();
   
     return <Link {...props} to={locacalizeTo(props.to, locale)} />;
   };
   

   En caso de que desee navegar a rutas localizadas, puede usar el hook useLocalizedNavigate:

   app/hooks/useLocalizedNavigate.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { useLocale } from "react-intlayer";
   import { type NavigateOptions, type To, useNavigate } from "react-router";
   
   import { locacalizeTo } from "~/components/localized-link";
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
     const { locale } = useLocale();
   
     const localizedNavigate = (to: To, options?: NavigateOptions) => {
       const localedTo = locacalizeTo(to, locale);
   
       navigate(localedTo, options);
     };
   
     return localizedNavigate;
   };
   

8. 8

   Utilize Intlayer in Your Pages

   Acceda a sus diccionarios de contenido en toda su aplicación:

   Página de inicio localizada

   Config-based routingFile-system routes

   app/routes/page.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { getIntlayer, validatePrefix } from "intlayer";
   import { useIntlayer } from "react-intlayer";
   import { data } from "react-router";
   
   import { LocaleSwitcher } from "~/components/locale-switcher";
   
   import { Navbar } from "~/components/navbar";
   import type { Route } from "./+types/page";
   
   export const loader = ({ params }: Route.LoaderArgs) => {
     const { locale } = params;
   
     const { isValid } = validatePrefix(locale);
   
     if (!isValid) {
       throw data("Locale not supported", { status: 404 });
     }
   };
   
   export const meta: Route.MetaFunction = ({ params }) => {
     const content = getIntlayer("page", params.locale);
   
     return [
       { title: content.title },
       { content: content.description, name: "description" },
     ];
   };
   
   export default function Page() {
     const { title, description, aboutLink } = useIntlayer("page");
   
     return (
       <div>
         <h1>{title}</h1>
         <p>{description}</p>
         <nav>
           <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
         </nav>
       </div>
     );
   }
   

   app/routes/($locale)._index.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { getIntlayer, validatePrefix } from "intlayer";
   import { useIntlayer } from "react-intlayer";
   import { data } from "react-router";
   
   import { LocaleSwitcher } from "~/components/locale-switcher";
   
   import { Navbar } from "~/components/navbar";
   import type { Route } from "./+types/($locale)._index";
   
   export const loader = ({ params }: Route.LoaderArgs) => {
     const { locale } = params;
   
     const { isValid } = validatePrefix(locale);
   
     if (!isValid) {
       throw data("Locale not supported", { status: 404 });
     }
   };
   
   export const meta: Route.MetaFunction = ({ params }) => {
     const content = getIntlayer("page", params.locale);
   
     return [
       { title: content.title },
       { content: content.description, name: "description" },
     ];
   };
   
   export default function Page() {
     const { title, description, aboutLink } = useIntlayer("page");
   
     return (
       <div>
         <h1>{title}</h1>
         <p>{description}</p>
         <nav>
           <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
         </nav>
       </div>
     );
   }
   

   Para aprender más sobre el hook useIntlayer, consulta la documentación.

   Si tu aplicación ya existe, puedes usar el Intlayer Compiler, así como el comando extract, para transformar miles de componentes en un segundo.

9. 9

   Crear un componente Locale Switcher

   Crea un componente para permitir que los usuarios cambien de idioma:

   Config-based routingFile-system routes

   app/components/locale-switcher.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     defaultLocale,
   } from "intlayer";
   import { useIntlayer, useLocale } from "react-intlayer";
   import { Link, useLocation } from "react-router";
   
   export const LocaleSwitcher: FC = () => {
     const { localeSwitcherLabel } = useIntlayer("locale-switcher");
     const { pathname } = useLocation();
   
     const { availableLocales, locale, setLocale } = useLocale();
   
     const pathWithoutLocale = getPathWithoutLocale(pathname);
   
     return (
       <ol>
         {availableLocales.map((localeItem) => (
           <li key={localeItem}>
             <Link
               aria-current={localeItem === locale ? "page" : undefined}
               aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
               onClick={() => setLocale(localeItem)}
               to={getLocalizedUrl(pathWithoutLocale, localeItem)}
             >
               <span>
                 {/* Locale - p. ej. FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Idioma en su propia configuración regional - p. ej. Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Idioma en la configuración regional actual - p. ej. Francés con la configuración regional actual establecida en Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={defaultLocale}>
                 {/* Idioma en inglés - p. ej. French */}
                 {getLocaleName(localeItem, defaultLocale)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

   app/components/locale-switcher.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     defaultLocale,
   } from "intlayer";
   import { useIntlayer, useLocale } from "react-intlayer";
   import { Link, useLocation } from "react-router";
   
   export const LocaleSwitcher: FC = () => {
     const { localeSwitcherLabel } = useIntlayer("locale-switcher");
     const { pathname } = useLocation();
   
     const { availableLocales, locale, setLocale } = useLocale();
   
     const pathWithoutLocale = getPathWithoutLocale(pathname);
   
     return (
       <ol>
         {availableLocales.map((localeItem) => (
           <li key={localeItem}>
             <Link
               aria-current={localeItem === locale ? "page" : undefined}
               aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
               onClick={() => setLocale(localeItem)}
               reloadDocument // Recarga la página para aplicar la nueva configuración regional
               to={getLocalizedUrl(pathWithoutLocale, localeItem)}
             >
               <span>
                 {/* Locale - p. ej. FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Idioma en su propia configuración regional - p. ej. Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Idioma en la configuración regional actual - p. ej. Francés con la configuración regional actual establecida en Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={defaultLocale}>
                 {/* Idioma en inglés - p. ej. French */}
                 {getLocaleName(localeItem, defaultLocale)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

   Para aprender más sobre el hook useLocale, consulta la documentación.

10. 10

    Agregar gestión de atributos HTML

    Crea un hook para gestionar los atributos lang y dir de HTML:

    app/hooks/useI18nHTMLAttributes.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { getHTMLTextDir } from "intlayer";
    import { useEffect } from "react";
    import { useLocale } from "react-intlayer";
    
    export const useI18nHTMLAttributes = () => {
      const { locale } = useLocale();
    
      useEffect(() => {
        document.documentElement.lang = locale;
        document.documentElement.dir = getHTMLTextDir(locale);
      }, [locale]);
    };
    

    Luego úsalo en tu componente raíz:

    app/routes/layout.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { Outlet } from "react-router";
    import { IntlayerProvider } from "react-intlayer";
    
    import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // importa el hook
    
    export default function RootLayout() {
      useI18nHTMLAttributes(); // llama el hook
    
      return (
        <IntlayerProvider>
          <Outlet />
        </IntlayerProvider>
      );
    }
    

11. 11

    Agregar middleware

    También puedes usar intlayerProxy para agregar enrutamiento del lado del servidor a tu aplicación. Este plugin detectará automáticamente la configuración regional actual basándose en la URL y establecerá la cookie de configuración regional apropiada. Si no se especifica una configuración regional, el plugin determinará la configuración regional más apropiada basándose en las preferencias de idioma del navegador del usuario. Si no se detecta ninguna configuración regional, redirigirá a la configuración regional predeterminada.

    Ten en cuenta que para usar intlayerProxy en producción, debes cambiar el paquete 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 ahora es opcional — se mantiene por compatibilidad con versiones anteriores 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 react from "@vitejs/plugin-react-swc";
    import { intlayer } from "vite-intlayer";
    
    // https://vitejs.dev/config/
    export default defineConfig({
      plugins: [
        react(),
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
      ],
    });
    

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 compiler / 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.
         *
         * - Si es `true`, el compilador reescribirá el archivo de componente en el disco. Entonces la transformación será permanente, y el compilador saltará la transformación para el próximo proceso. De esta manera, el compilador puede transformar la aplicación y luego puede ser removido.
         *
         * - Si es `false`, el compilador inyectará la llamada de función `useIntlayer()` en el código solo en la salida de compilación, y mantendrá la base de código intacta. La transformación se realizará solo en memoria.
         */
        saveComponents: false,
    
        /**
         * Prefijo de clave de diccionario
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Extract commandBabel compiler

    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
    

    Desde v9, el intlayerCompiler está incluido en el plugin intlayer. Por lo tanto, no necesitas agregarlo manualmente.

    Actualiza tu 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 compilador
      ],
    });
    

    bash

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    npm run build # O npm run dev
    

Configurar TypeScript

Intlayer utiliza module augmentation para aprovechar los beneficios de TypeScript y fortalecer tu codebase.

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

{
  // ... tus configuraciones existentes
  include: [
    // ... tus includes existentes
    ".intlayer/**/*.ts", // Incluye los tipos autogenerados
  ],
}

Configuración de Git

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

Para hacerlo, puedes añadir 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 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.

Referencias de Documentación

• Documentación de Intlayer
• Documentación de React Router v7
• Hook useIntlayer
• Hook useLocale
• Declaración de Contenido
• Configuración

Esta guía completa te proporciona todo lo que necesitas para integrar Intlayer con React Router v7 para una aplicación completamente internacionalizada con enrutamiento consciente de la configuración regional y soporte para TypeScript.

Preguntas frecuentes