Traduce tu sitio web Tanstack Start usando Intlayer | Internacionalización (i18n)

Tabla de contenidos

Esta guía demuestra cómo integrar Intlayer para una internacionalización fluida en proyectos Tanstack Start con enrutamiento consciente de la configuración regional, soporte para TypeScript y prácticas de desarrollo modernas.

¿Por qué Intlayer en lugar de alternativas?

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

Guía paso a paso para configurar Intlayer en una aplicación Tanstack Start

VídeoCódigoDemo

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-tanstack-start-template.vercel.app

Open embedded page in fullscreen

Consulta la Plantilla de Aplicación en GitHub.

1. 1

   Crear proyecto

   Comienza creando un nuevo proyecto TanStack Start siguiendo la guía Start new project en el sitio web de TanStack Start.

2. 2

   Instalar paquetes de Intlayer

   Instala los paquetes necesarios utilizando 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á su entorno e instalará los paquetes necesarios. 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 la 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 empaquetador Vite, así como el middleware para detectar la configuración regional preferida del usuario, gestionar cookies y manejar la redirección de URL.

3. 3

   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 } from "intlayer";
   
   import { 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 establecer 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.

4. 4

   Integrar Intlayer en tu configuración de Vite

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

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { tanstackStart } from "@tanstack/react-start/plugin/vite";
   import viteReact from "@vitejs/plugin-react";
   import { nitro } from "nitro/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   const config = defineConfig({
     plugins: [
       nitro(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
       tanstackStart({
         router: {
           routeFileIgnorePattern:
             ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
         },
       }),
       viteReact(),
     ],
   });
   
   export default config;
   

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

5. 5

   Crear el diseño raíz

   Configura tu diseño raíz para admitir la internacionalización mediante el uso de useParams para detectar la configuración regional actual y estableciendo los atributos lang y dir en la etiqueta html.

   src/routes/__root.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import {
     createRootRouteWithContext,
     getRouteApi,
     HeadContent,
     Scripts,
   } from "@tanstack/react-router";
   import { defaultLocale, getHTMLTextDir } from "intlayer";
   import { type ReactNode } from "react";
   import { IntlayerProvider } from "react-intlayer";
   
   const localeRoute = getRouteApi("/{-$locale}");
   
   export const Route = createRootRouteWithContext<{}>()({
     head: () => ({
       meta: [
         {
           charSet: "utf-8",
         },
         {
           content: "width=device-width, initial-scale=1",
           name: "viewport",
         },
         {
           title: "TanStack Start Starter",
         },
       ],
     }),
   
     shellComponent: RootDocument,
   });
   
   function RootDocument({ children }: { children: ReactNode }) {
     const params = localeRoute.useParams();
     const locale = params?.locale ?? defaultLocale;
   
     return (
       <html dir={getHTMLTextDir(locale)} lang={locale}>
         <head>
           <HeadContent />
         </head>
         <body>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
           <Scripts />
         </body>
       </html>
     );
   }
   

6. 6

   Crear el diseño de configuración regional

   Crea un diseño que maneje el prefijo de configuración regional y realice la validación.

   src/routes/{-$locale}/route.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
   import { validatePrefix } from "intlayer";
   
   export const Route = createFileRoute("/{-$locale}")({
     beforeLoad: ({ params }) => {
       const localeParam = params.locale;
   
       // Validar el prefijo de configuración regional
       const { isValid, localePrefix } = validatePrefix(localeParam);
   
       if (!isValid) {
         throw redirect({
           to: "/{-$locale}/404",
           params: { locale: localePrefix },
         });
       }
     },
     component: Outlet,
   });
   

   Aquí, {-$locale} es un parámetro de ruta dinámica que se reemplaza con la configuración regional actual. Esta notación hace que el espacio sea opcional, permitiendo que funcione con modos de enrutamiento como 'prefix-no-default', etc.

   Ten en cuenta que este espacio puede causar problemas si utilizas múltiples segmentos dinámicos en la misma ruta (por ejemplo, /{-$locale}/otra-ruta/$otroCaminoDinamico/...). Para el modo 'prefix-all', es posible que prefieras cambiar el espacio a $locale en su lugar. Para el modo 'no-prefix' o 'search-params', puedes eliminar el espacio por completo.

7. 7

   Declarar tu contenido

   Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

   src/contents/page.content.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { Dictionary } from "intlayer";
   
   import { t } from "intlayer";
   
   const appContent = {
     content: {
       links: {
         about: t({
           en: "About",
           es: "Acerca de",
           fr: "À propos",
         }),
         home: t({
           en: "Home",
           es: "Inicio",
           fr: "Accueil",
         }),
       },
       meta: {
         title: t({
           en: "Welcome to Intlayer + TanStack Router",
           es: "Bienvenido a Intlayer + TanStack Router",
           fr: "Bienvenue à Intlayer + TanStack Router",
         }),
         description: t({
           en: "This is an example of using Intlayer with TanStack Router",
           es: "Este es un ejemplo de uso de Intlayer con TanStack Router",
           fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router",
         }),
       },
     },
     key: "app",
   } satisfies Dictionary;
   
   export default appContent;
   

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

8. 7

   Crear componentes y hooks conscientes de la configuración regional

   Crea un componente LocalizedLink para la navegación consciente de la configuración regional:

   src/components/localized-link.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import type { FC } from "react";
   
   import { Link, type LinkComponentProps } from "@tanstack/react-router";
   import { useLocale } from "react-intlayer";
   import { getPrefix } from "intlayer";
   
   export const LOCALE_ROUTE = "{-$locale}" as const;
   
   export type To = StripLocalePrefix<LinkComponentProps["to"]>;
   
   export type StripLocalePrefix<T extends string | undefined> = T extends
     `/${typeof LOCALE_ROUTE}/` | `/${typeof LOCALE_ROUTE}`
     ? "/"
     : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
       ? `/${Rest}`
       : T;
   
   type LocalizedLinkProps = {
     to?: To;
   } & Omit<LinkComponentProps, "to">;
   
   export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
     const { locale } = useLocale();
     const { localePrefix } = getPrefix(locale);
   
     return (
       <Link
         {...props}
         params={{
           locale: localePrefix,
           ...(typeof props?.params === "object" ? props?.params : {}),
         }}
         to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]}
       />
     );
   };
   

   Este componente tiene dos objetivos:

   • Eliminar el prefijo innecesario {-$locale} de la URL.
   • Inyectar el parámetro de configuración regional en la URL para garantizar que el usuario sea redirigido directamente a la ruta localizada.

   Luego podemos crear un hook useLocalizedNavigate para la navegación programática:

   src/hooks/useLocalizedNavigate.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { useNavigate } from "@tanstack/react-router";
   import { getPrefix } from "intlayer";
   import { useLocale } from "react-intlayer";
   import type { StripLocalePrefix } from "@/components/localized-link";
   import type { FileRouteTypes } from "@/routeTree.gen";
   
   type NavigateFn = ReturnType<typeof useNavigate>;
   type BaseNavigateOptions = Parameters<NavigateFn>[0];
   
   type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;
   
   export type LocalizedNavigateOptions = Omit<
     BaseNavigateOptions,
     "to" | "params"
   > & {
     to: LocalizedTo;
     params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
   };
   
   type LocalizedNavigate = (
     options: LocalizedNavigateOptions
   ) => ReturnType<NavigateFn>;
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
   
     const { locale } = useLocale();
   
     const localizedNavigate: LocalizedNavigate = (args: any) => {
       const { localePrefix } = getPrefix(locale);
   
       if (typeof args === "string") {
         return navigate({
           to: `/${LOCALE_ROUTE}${args}`,
           params: { locale: localePrefix },
         });
       }
   
       const { to, ...rest } = args;
   
       const localizedTo = `/${LOCALE_ROUTE}${to}` as any;
   
       return navigate({
         to: localizedTo,
         params: { locale: localePrefix, ...rest } as any,
       });
     };
   
     return localizedNavigate;
   };
   

9. 8

   Utilizar Intlayer en tus páginas

   Usa useIntlayer por defecto: es la forma recomendada de leer contenido dentro de los componentes, y el compilador lo resuelve a la locale que se está renderizando. Recurre a getIntlayer / getIntlayerAsync solo fuera del árbol de React: el head de las rutas, los loaders y las server functions.

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

   Página de Inicio Localizada

   src/routes/{-$locale}/index.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { createFileRoute } from "@tanstack/react-router";
   import { useIntlayer } from "react-intlayer";
   
   import LocaleSwitcher from "@/components/locale-switcher";
   import { LocalizedLink } from "@/components/localized-link";
   import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";
   
   export const Route = createFileRoute("/{-$locale}/")({
     component: RouteComponent,
   });
   
   function RouteComponent() {
     const content = useIntlayer("app");
     const navigate = useLocalizedNavigate();
   
     return (
       <div>
         <div>
           {content.title}
           <LocaleSwitcher />
           <div>
             <LocalizedLink to="/">{content.links.home}</LocalizedLink>
             <LocalizedLink to="/about">{content.links.about}</LocalizedLink>
           </div>
           <div>
             <button onClick={() => navigate({ to: "/" })}>
               {content.links.home}
             </button>
             <button onClick={() => navigate({ to: "/about" })}>
               {content.links.about}
             </button>
           </div>
         </div>
       </div>
     );
   }
   

   Si deseas usar tu contenido en un atributo string, como alt, title, href, aria-label, etc., puedes usar el 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)}" />
   

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

10. 9

    Crear un Componente de Selector de Idioma

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

    src/components/locale-switcher.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { useLocation } from "@tanstack/react-router";
    import {
      getHTMLTextDir,
      getLocaleName,
      getPathWithoutLocale,
      getPrefix,
      Locales,
    } from "intlayer";
    import type { FC } from "react";
    import { useLocale } from "react-intlayer";
    
    import { LocalizedLink, type To } from "./localized-link";
    
    export const LocaleSwitcher: FC = () => {
      const { pathname } = useLocation();
    
      const { availableLocales, locale, setLocale } = useLocale();
    
      const pathWithoutLocale = getPathWithoutLocale(pathname);
    
      return (
        <ol>
          {availableLocales.map((localeEl) => (
            <li key={localeEl}>
              <LocalizedLink
                aria-current={localeEl === locale ? "page" : undefined}
                onClick={() => setLocale(localeEl)}
                params={{ locale: getPrefix(localeEl).localePrefix }}
                to={pathWithoutLocale as To}
              >
                <span>
                  {/* Idioma - p.ej. FR */}
                  {localeEl}
                </span>
                <span>
                  {/* Idioma en su propia localización - p.ej. Français */}
                  {getLocaleName(localeEl, locale)}
                </span>
                <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
                  {/* Idioma en la localización actual - p.ej. Francés con la localización actual establecida a Locales.SPANISH */}
                  {getLocaleName(localeEl)}
                </span>
                <span dir="ltr" lang={Locales.ENGLISH}>
                  {/* Idioma en inglés - p.ej. French */}
                  {getLocaleName(localeEl, Locales.ENGLISH)}
                </span>
              </LocalizedLink>
            </li>
          ))}
        </ol>
      );
    };
    

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

11. 10

    Gestión de Atributos HTML

    Como se vio en el Paso 5, puedes gestionar los atributos lang y dir de la etiqueta html usando useParams en tu componente raíz. Esto asegura que los atributos correctos se establezcan en el servidor y cliente.

    src/routes/__root.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    const localeRoute = getRouteApi("/{-$locale}");
    
    function RootDocument({ children }: { children: ReactNode }) {
      const params = localeRoute.useParams();
      const locale = params?.locale ?? defaultLocale;
    
      return (
        <html dir={getHTMLTextDir(locale)} lang={locale}>
          {/* ... */}
        </html>
      );
    }
    

12. 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 localización actual basándose en la URL y establecerá la cookie de localización apropiada. Si no se especifica una localización, el plugin determinará la localización más apropiada según las preferencias de idioma del navegador del usuario. Si no se detecta ninguna localización, redirigirá a la localización predeterminada.

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

    Desde Intlayer v9, intlayerProxy() está agrupado directamente en el plugin intlayer() y habilitado de forma predeterminada mediante la opción routing.enableProxy (true de forma predeterminada). Registrarlo por separado como se muestra a continuación ahora es opcional: se mantiene para compatibilidad hacia atrás y para configuraciones que necesitan controlar el orden del plugin. 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 { tanstackStart } from "@tanstack/react-start/plugin/vite";
    import viteReact from "@vitejs/plugin-react";
    import { nitro } from "nitro/vite";
    import { defineConfig } from "vite";
    import { intlayer } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        nitro(),
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
        tanstackStart({
          router: {
            routeFileIgnorePattern:
              ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
          },
        }),
        viteReact(),
      ],
    });
    

13. 12

    Internacionalizar tus Metadatos

    Resolución estáticaResolución dinámicaResolución dinámica en caché

    getIntlayer se resuelve de forma sincrónica contra el diccionario combinado, el que contiene todas las localizaciones declaradas. head permanece sincrónico y no se espera nada, pero todo el diccionario multilingüe se extrae en el chunk de ruta enviado al navegador.

    src/routes/{-$locale}/index.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayer,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // La ruta para esta página
    
        const metaContent = getIntlayer("app", locale);
    
        return {
          links: [
            // Enlace canónico: Apunta a la página localizada actual
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Informa a Google sobre todas las versiones localizadas
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: Para usuarios en idiomas no coincidentes
            // Define la localización de reserva predeterminada (normalmente tu idioma principal)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Mejor para diccionarios de metadatos pequeños, un puñado de localizaciones, o mientras prototipas.

    getIntlayerAsync (disponible desde v9.4) se comporta como getIntlayer, pero el plugin de compilación lo apunta al chunk por localización en .intlayer/dynamic_dictionaries/ en lugar del diccionario combinado. Una página, por lo tanto, envía solo la localización que renderiza. Porque ese chunk se carga bajo demanda, head se vuelve async:

    src/routes/{-$locale}/index.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: async ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // La ruta para esta página
    
        const metaContent = await getIntlayerAsync("app", locale);
    
        return {
          links: [
            // Enlace canónico: Apunta a la página localizada actual
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Informa a Google sobre todas las versiones localizadas
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: Para usuarios en idiomas no coincidentes
            // Define la localización de reserva predeterminada (normalmente tu idioma principal)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Si un head lee varios diccionarios, resuélvelos con Promise.all: esperar cada getIntlayerAsync en su propia línea encadena las solicitudes en lugar de ejecutarlas en paralelo.

    La compensación: la importación dinámica se resuelve mientras se ejecuta head, en la ruta crítica del renderizado del documento. En una ruta fría, esto retrasa el head por unos pocos milisegundos y puede degradar ligeramente el LCP.

    Resuelve el diccionario en el loader de la ruta y léelo desde loaderData en head. Los loaders de las rutas coincidentes se ejecutan en paralelo, y staleTime: Infinity le dice a TanStack Router que el resultado nunca queda obsoleto, por lo que el chunk por localización se resuelve una sola vez y se sirve desde la caché del router después, dejando head sincrónico.

    src/routes/{-$locale}/index.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      // Resuelto en paralelo con las otras rutas coincidentes, fuera de la ruta crítica del head
      loader: async ({ params }) => {
        const { locale = defaultLocale } = params;
    
        return { metaContent: await getIntlayerAsync("app", locale) };
      },
      // El diccionario nunca cambia para una localización dada: resuelve el chunk una sola vez
      staleTime: Infinity,
      head: ({ params, loaderData }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // La ruta para esta página
    
        return {
          links: [
            // Enlace canónico: Apunta a la página localizada actual
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Informa a Google sobre todas las versiones localizadas
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: Para usuarios en idiomas no coincidentes
            // Define la localización de reserva predeterminada (normalmente tu idioma principal)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: loaderData?.metaContent.title },
            {
              name: "description",
              content: loaderData?.metaContent.meta.description,
            },
          ],
        };
      },
    });
    

    head puede ser llamado antes de que el loader se resuelva, por lo que loaderData se tipifica como posiblemente undefined. Mantén el optional chaining, o devuelve un título de reserva.

    Mantienes el chunk por localización sin pagar su costo en la ruta crítica del head. El precio es la experiencia del desarrollador: el contenido debe pasarse explícitamente desde el loader al head a través de loaderData.

    ¿Qué resolución debo elegir?

    Mostrar todo el contenido de la tabla

    Mostrar todo el contenido de la tabla

    Abrir la tabla en una ventana flotante para ver todo el contenido claramente

    	Resolución estática	Resolución dinámica	Resolución dinámica en caché
    API	getIntlayer	getIntlayerAsync (v9.4+)	getIntlayerAsync in loader (v9.4+)
    Firma de head	synchronous	async	synchronous, reads loaderData
    Locales enviados	every declared locale	requested locale only	requested locale only
    Navegaciones de cliente	nothing to resolve	re-entered on every match	served from the router cache
    Experiencia del desarrollador	simplest	one await	content threaded through loaderData

14. 13

    Recuperar la localización en tus acciones de servidor

    Puede que quieras acceder a la localización actual desde tus acciones de servidor o puntos finales de API. Puedes hacerlo usando el helper getLocale de intlayer.

    Aquí hay un ejemplo usando funciones de servidor de TanStack Start:

    src/routes/{-$locale}/index.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { createServerFn } from "@tanstack/react-start";
    import {
      getRequestHeader,
      getRequestHeaders,
    } from "@tanstack/react-start/server";
    import { getCookie, getIntlayer, getLocale } from "intlayer";
    
    export const getLocaleServer = createServerFn().handler(async () => {
      const locale = await getLocale({
        // Obtén la cookie de la solicitud (por defecto: 'INTLAYER_LOCALE')
        getCookie: (name) => {
          const cookieString = getRequestHeader("cookie");
    
          return getCookie(name, cookieString);
        },
        // Obtén el encabezado de la solicitud (por defecto: 'x-intlayer-locale')
        // Fallback usando negociación Accept-Language
        getHeader: (name) => getRequestHeader(name),
      });
    
      // Recupera contenido usando getIntlayerAsync()
      const content = getIntlayer("app", locale);
    
      return { locale, content };
    });
    

15. 14

    Gestionar páginas no encontradas

    Cuando un usuario visita una página que no existe, puedes mostrar una página de no encontrado personalizada y el prefijo de configuración regional puede afectar la forma en que se activa la página de no encontrado.

    Entender el manejo de 404 de TanStack Router con prefijos de configuración regional

    En TanStack Router, el manejo de páginas 404 con rutas localizadas requiere un enfoque multicapa:

    1. Ruta 404 dedicada: Una ruta específica para mostrar la interfaz de usuario 404.
    2. Validación a nivel de ruta: Valida los prefijos de configuración regional y redirige los inválidos a 404.
    3. Ruta catch-all: Captura cualquier ruta no coincidente dentro del segmento de configuración regional.

    src/routes/{-$locale}/404.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute } from "@tanstack/react-router";
    
    // Esto crea una ruta dedicada /[locale]/404
    // Se utiliza tanto como una ruta directa como importada como componente en otros archivos
    export const Route = createFileRoute("/{-$locale}/404")({
      component: NotFoundComponent,
    });
    
    // Exportado por separado para que pueda reutilizarse en notFoundComponent y rutas catch-all
    export function NotFoundComponent() {
      return (
        <div>
          <h1>404</h1>
        </div>
      );
    }
    

    src/routes/{-$locale}/route.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
    import { validatePrefix } from "intlayer";
    import { NotFoundComponent } from "./404";
    
    export const Route = createFileRoute("/{-$locale}")({
      // beforeLoad se ejecuta antes de que la ruta se renderice (tanto en el servidor como en el cliente)
      // Es el lugar ideal para validar el prefijo de configuración regional
      beforeLoad: ({ params }) => {
        const localeParam = params.locale;
    
        // validatePrefix comprueba si la configuración regional es válida según tu configuración de intlayer
        const { isValid, localePrefix } = validatePrefix(localeParam);
    
        if (!isValid) {
          // Prefijo de configuración regional inválido - redirigir a la página 404 con un prefijo de configuración regional válido
          throw redirect({
            to: "/{-$locale}/404",
            params: { locale: localePrefix },
          });
        }
      },
      component: Outlet,
      // notFoundComponent se llama cuando una ruta hija no existe
      // p. ej., /en/pagina-inexistente activa esto dentro del diseño /en
      notFoundComponent: NotFoundComponent,
    });
    

    src/routes/{-$locale}/$.tsx

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute } from "@tanstack/react-router";
    
    import { NotFoundComponent } from "./404";
    
    // La ruta $ (splat/catch-all) coincide con cualquier ruta que no coincida con otras rutas
    // p. ej., /en/algun/camino/profundo/anidado/invalido
    // Esto garantiza que TODAS las rutas no coincidentes dentro de una configuración regional muestren la página 404
    // Sin esto, las rutas profundas no coincidentes podrían mostrar una página en blanco o un error
    export const Route = createFileRoute("/{-$locale}/$")({
      component: NotFoundComponent,
    });
    

16. 15

    Extraer el contenido de tus componentes

    Opcional

    isOptional={true}>

    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
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    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(), // Adds the compiler plugin
      ],
    });
    

    bash

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    npm run build # O npm run dev
    

17. 16

    Generar un Sitemap

    Intlayer viene con un generador de sitemap integrado para ayudarte a crear fácilmente un sitemap para tu aplicación. Maneja las rutas localizadas y agrega los metadatos necesarios para los motores de búsqueda.

    El sitemap generado por Intlayer admite el espacio de nombres xhtml:link (Hreflang XML Extensions). A diferencia de los generadores de sitemap predeterminados que solo enumeran URL sin procesar, Intlayer crea automáticamente los enlaces bidireccionales necesarios entre todas las versiones de idioma de una página (por ejemplo, /about, /about?lang=fr y /about?lang=es). Esto garantiza que los motores de búsqueda indexen y sirvan correctamente la versión de idioma adecuada a la audiencia adecuada.

    Para usarlo, primero debes configurar tu archivo vite.config.ts para habilitar el prerrenderizado de tus rutas localizadas y deshabilitar la generación de sitemap predeterminada de TanStack Start.

    vite.config.ts

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { localeFlatMap } from "intlayer";
    // ... otras importaciones
    
    export const pathList = ["", "/about", "/404"];
    
    const localizedPages = localeFlatMap(({ urlPrefix }) =>
      pathList.map((path) => ({
        path: `${urlPrefix}${path}`,
        prerender: {
          enabled: true,
        },
      }))
    );
    
    export default defineConfig({
      plugins: [
        // ... otros plugins
        tanstackStart({
          // ... otras configuraciones
          sitemap: {
            enabled: false,
          },
          prerender: {
            enabled: true,
            crawlLinks: false,
            concurrency: 10,
          },
          pages: localizedPages,
        }),
      ],
    });
    

    Luego, crea una ruta src/routes/sitemap[.]xml.ts que use la función generateSitemap:

    src/routes/sitemap[.]xml.ts

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute } from "@tanstack/react-router";
    import { generateSitemap } from "intlayer";
    
    const SITE_URL = (
      import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
    ).replace(/\/$/, "");
    
    export const Route = createFileRoute("/sitemap.xml")({
      server: {
        handlers: {
          GET: async () => {
            const sitemap = generateSitemap(
              [
                { path: "/", changefreq: "daily", priority: 1.0 },
                { path: "/about", changefreq: "monthly", priority: 0.8 },
              ],
              { siteUrl: SITE_URL }
            );
    
            return new Response(sitemap, {
              headers: { "Content-Type": "application/xml" },
            });
          },
        },
      },
    });
    

18. 17

    Configurar TypeScript

    Intlayer utiliza la ampliación de módulos para obtener los beneficios de TypeScript y fortalecer tu base de código.

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

    tsconfig.json

    Copiar contenido

    Copiar código

    Copiar el código al portapapeles

    {
      // ... tus configuraciones existentes
      include: [
        // ... tus inclusiones existentes
        ".intlayer/**/*.ts", // Incluir 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 ello, 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.
• Previsualizaciones inline 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 allá

Para ir más allá, puedes implementar el editor visual o externalizar tu contenido usando el CMS.

Referencias de Documentación

• Documentación de Intlayer
• Documentación de Tanstack Start
• Hook useIntlayer
• Hook useLocale
• Declaración de Contenido
• Configuración

Preguntas frecuentes