InicioEntorno de pruebasExhibiciónAppDocBlog
    • Englishinglés
      EN
    • русскийruso
      RU
    • 日本語japonés
      JA
    • françaisfrancés
      FR
    • 한국어coreano
      KO
    • 中文chino
      ZH
    • españolespañol
      ES
    • Deutschalemán
      DE
    • العربيةárabe
      AR
    • italianoitaliano
      IT
    • British Englishinglés británico
      EN-GB
    • portuguêsportugués
      PT
    • हिन्दीhindi
      HI
    • Türkçeturco
      TR
    • polskipolaco
      PL
    • Indonesiaindonesio
      ID
    • Tiếng Việtvietnamita
      VI
    • українськаucraniano
      UK
    /
    Filtrar documentación por framework
    Alt+←
    ¿Por qué Intlayer?
    Empezar
    Concepto
    • Cómo funciona Intlayer
    • Configuración
    • TestFillBuildWatchExtractLoginPushPullConfigurationListVersionEditorLiveDebugDoc ReviewDoc TranslateSDK
    • Editor visual
    • CMS
    • Integración CI/CD
    • TraducciónPluralEnumeraciónCondiciónGéneroInserciónArchivoAnidaciónMarkdownHTMLObtención de función
    • Archivo por locale
    • Compilador
    • Autocompletado
    • Pruebas
    • Optimización de bundle
    Entornos
    • Next.js 14 y App Router
      Next.js 15
      Next.js sin locale URL
      Next.js y Page Router
      Compiler
    • Tanstack Start Solid
    • Astro y React
      Astro y Svelte
      Astro y Vue
      Astro y Solid
      Astro y Preact
      Astro y Lit
      Astro y Vanilla JS
    • React Router v7
      React Router v7 (fs-routes)
      Compiler
    • Nuxt y Vue
    • Vite y Solid
    • SvelteKit
    • Vite y Preact
    • Vite y Vanilla JS
    • Vite y Lit
    • Angular 19 (Webpack)
      Analog
    • React CRA
    • React Native y Expo
    • Express.js
      NestJS
      Fastify
      Hono
      Adonis
    • Lynx y React
    Plugins
    • JSON
    • gettext (.po)
    Extensión VS Code
    Agente
    • Servidor MCP
    • Habilidades del agente
    Versiones
    • v8
    • v7
    • v6
    Benchmark
    • Next.js
    • TanStack
    • Vue
    • Solid
    • Svelte
    Blog
    Preguntar una pregunta
    1. Documentation
    2. Entornos
    3. Tanstack Start
    Creación:2025-09-09Última actualización:2026-05-06
    Ver la plantilla de aplicación en GitHub

    Esta página tiene una plantilla de aplicación disponible.

    Ver la aplicación de demostración

    Esta página enlaza a una demo en vivo de la plantilla.

    Ver el video tutorial

    Esta página tiene un video tutorial disponible.

    Referencia esta doc a tu asistente AI favorito
    ChatGPT
    Claude
    DeepSeek
    Google AI mode
    Gemini
    Perplexity
    Mistral
    Grok

    Haz tu pregunta y obtén un resumen del documento referenciando esta página y el proveedor AI de tu elección

    Historial de versiones

    1. "Actualizar el uso de la API useIntlayer de Solid para el acceso directo a las propiedades"
      v8.9.04/5/2026
    2. "Añadir comando init"
      v7.5.930/12/2025
    3. "Introducir validatePrefix y añadir el paso 14: Gestión de páginas 404 con rutas localizadas."
      v7.4.011/12/2025
    4. "Añadir el paso 13: Obtener la configuración regional en tus acciones del servidor (Opcional)"
      v7.3.95/12/2025
    5. "Añadir el paso 13: Adaptar Nitro"
      v7.2.318/11/2025
    6. "Corregir prefijo por defecto añadiendo la función getPrefix, useLocalizedNavigate, LocaleSwitcher y LocalizedLink."
      v7.1.017/11/2025
    7. "Actualizar documento"
      v6.5.23/10/2025
    8. "Añadido para Tanstack Start"
      v5.8.19/9/2025

    El contenido de esta página ha sido traducido con una IA.

    Ver la última versión del contenido original en inglés
    Editar esta documentación

    Si tienes una idea para mejorar esta documentación, no dudes en contribuir enviando una pull request en GitHub.

    Enlace de GitHub a la documentación
    Copiar

    Copiar el Markdown del documento a la portapapeles

    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.

    ¿Qué es Intlayer?

    Intlayer es una biblioteca de internacionalización (i18n) innovadora y de código abierto diseñada para simplificar el soporte multilingüe en aplicaciones web modernas.

    Con Intlayer, puedes:

    • Gestionar fácilmente las traducciones utilizando diccionarios declarativos a nivel de componente.
    • Localizar dinámicamente metadatos, rutas y contenido.
    • Garantizar el soporte de TypeScript con tipos autogenerados, mejorando el autocompletado y la detección de errores.
    • Beneficiarte de funciones avanzadas, como la detección y el cambio dinámico de la configuración regional.
    • Habilitar el enrutamiento consciente de la configuración regional con el sistema de enrutamiento basado en archivos de Tanstack Start.

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

    www.youtube.com
    ide.intlayer.org
    intlayer-tanstack-start-template.vercel.app

    Consulta la Plantilla de Aplicación en GitHub.

    Paso 1: Crear proyecto

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

    Paso 2: Instalar paquetes de Intlayer

    Instala los paquetes necesarios utilizando tu gestor de paquetes preferido:

    bash
    Copiar código

    Copiar el código al portapapeles

    npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init
    • intlayer

      El paquete principal que proporciona herramientas de internacionalización para la gestión de la configuración, traducción, declaración de contenido, 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.

    Paso 3: Configuración de tu proyecto

    Crea un archivo de configuración para configurar los idiomas de tu aplicación:

    intlayer.config.ts
    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.

    Paso 4: Integrar Intlayer en tu configuración de Vite

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

    vite.config.ts
    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(),    tanstackStart({      router: {        routeFileIgnorePattern:          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",      },    }),    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.

    Paso 5: Crear el diseño raíz (Root Layout)

    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 código

    Copiar el código al portapapeles

    import {  createRootRouteWithContext,  HeadContent,  Scripts,} from "@tanstack/react-router";import { defaultLocale, getHTMLTextDir } from "intlayer";import { type ReactNode } from "react";import { IntlayerProvider } from "react-intlayer";import { Route as LocaleRoute } from "./{-$locale}/route";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>  );}
    Si deseas usar tu contenido en un atributo de tipo string, como alt, title, href, aria-label, etc., debes llamar al valor de la función, así:
    html
    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)}" />

    Paso 6: Crear el diseño de configuración regional (Locale Layout)

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

    src/routes/{-$locale}/route.tsx
    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.

    Paso 7: Declarar tu contenido

    Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

    src/contents/page.content.ts
    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}).
    Para más detalles, consulta la documentación de declaración de contenido.

    Paso 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 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 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;};

    Paso 8: Utilizar Intlayer en tus páginas

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

    Página de inicio localizada

    src/routes/{-$locale}/index.tsx
    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";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>  );}
    Para obtener más información sobre el hook useIntlayer, consulta la documentación.

    Paso 9: Crear un componente selector de idioma (Locale Switcher)

    Crea un componente para permitir a los usuarios cambiar de idioma:

    src/components/locale-switcher.tsx
    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>              {/* Configuración regional - p. ej. FR */}              {localeEl}            </span>            <span>              {/* Idioma en su propia configuración regional - p. ej. Français */}              {getLocaleName(localeEl, locale)}            </span>            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>              {/* Idioma en la configuración regional actual - p. ej. Francés con la configuración regional actual establecida en 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.

    Paso 10: Gestión de atributos HTML

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

    src/routes/__root.tsx
    Copiar código

    Copiar el código al portapapeles

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

    Paso 11: Añadir middleware (Opcional)

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

    Ten en cuenta que para usar el intlayerProxy en producción, necesitas cambiar el paquete vite-intlayer de devDependencies a dependencies.
    vite.config.ts
    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, intlayerProxy } from "vite-intlayer";export default defineConfig({  plugins: [    intlayerProxy(), // El proxy debe colocarse antes que el servidor si utilizas Nitro    nitro(),    intlayer(),    tanstackStart({      router: {        routeFileIgnorePattern:          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",      },    }),    viteReact(),  ],});

    Paso 12: Internacionalizar tus metadatos (Opcional)

    También puedes usar el hook getIntlayer para acceder a tus diccionarios de contenido en toda tu aplicación:

    src/routes/{-$locale}/index.tsx
    Copiar código

    Copiar el código al portapapeles

    import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";export const Route = createFileRoute("/{-$locale}/")({  component: RouteComponent,  head: ({ params }) => {    const { locale } = params;    const path = "/"; // The path for this route    const metaContent = getIntlayer("app", locale);    return {      links: [        // Canonical link: Points to the current localized page        { rel: "canonical", href: getLocalizedUrl(path, locale) },        // Hreflang: Tell Google about all localized versions        ...localeMap(({ locale: mapLocale }) => ({          rel: "alternate",          hrefLang: mapLocale,          href: getLocalizedUrl(path, mapLocale),        })),        // x-default: For users in unmatched languages        // Define the default fallback locale (usually your primary language)        {          rel: "alternate",          hrefLang: "x-default",          href: getLocalizedUrl(path, defaultLocale),        },      ],      meta: [        { title: metaContent.title },        { name: "description", content: metaContent.meta.description },      ],    };  },});

    Paso 13: Recuperar la configuración regional en tus acciones del servidor (Opcional)

    Es posible que desees acceder a la configuración regional actual desde dentro de tus acciones del servidor o endpoints de la API. Puedes hacerlo utilizando el asistente getLocale de intlayer.

    Aquí tienes un ejemplo utilizando las funciones del servidor de TanStack Start:

    src/routes/{-$locale}/index.tsx
    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({    // Obtener la cookie de la solicitud (por defecto: 'INTLAYER_LOCALE')    getCookie: (name) => {      const cookieString = getRequestHeader("cookie");      return getCookie(name, cookieString);    },    // Obtener el encabezado de la solicitud (por defecto: 'x-intlayer-locale')    // Respaldo mediante negociación Accept-Language    getHeader: (name) => getRequestHeader(name),  });  // Recuperar algún contenido usando getIntlayer()  const content = getIntlayer("app", locale);  return { locale, content };});

    Paso 14: Gestionar páginas no encontradas (Opcional)

    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 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 archivosexport const Route = createFileRoute("/{-$locale}/404")({  component: NotFoundComponent,});// Exportado por separado para que pueda reutilizarse en notFoundComponent y rutas catch-allexport function NotFoundComponent() {  return (    <div>      <h1>404</h1>    </div>  );}
    src/routes/{-$locale}/route.tsx
    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 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 errorexport const Route = createFileRoute("/{-$locale}/$")({  component: NotFoundComponent,});

    (Opcional) Paso 15 : Extraer el contenido de tus componentes

    Si tienes una base de código existente, transformar miles de archivos puede llevar mucho tiempo.

    Para facilitar este proceso, Intlayer propone un compilador / 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 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;

    Ejecuta el extractor para transformar tus componentes y extraer el contenido

    bash
    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 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 código

    Copiar el código al portapapeles

    npm run build # O npm run dev

    Paso 16: Generar un Sitemap (Opcional)

    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 código

    Copiar el código al portapapeles

    import { localeFlatMap } from "intlayer";// ... otras importacionesexport 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 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" },        });      },    },  },});

    Paso 17: Configurar TypeScript (Opcional)

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

    .gitignore
    Copiar código

    Copiar el código al portapapeles

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

    Esta extensión proporciona:

    • Autocompletado para las claves de traducción.
    • Detección de errores en tiempo real para las traducciones que faltan.
    • Vistas previas en línea del contenido traducido.
    • Acciones rápidas para crear y actualizar traducciones fácilmente.

    Para obtener más detalles sobre cómo utilizar la extensión, consulta la documentación de la extensión de VS Code de Intlayer.


    Ir más allá

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


    Referencias de la documentación

    • Documentación de Intlayer
    • Documentación de Tanstack Start
    • Hook useIntlayer
    • Hook useLocale
    • Declaración de contenido
    • Configuración
    Compiler
    Tanstack Start Solid
    Alt+→

    En esta página

      Las conversaciones son anónimas y se revisan regularmente para abordar problemas comunes. No dudes en compartir ideas de funcionalidades, comentarios sobre la documentación o cualquier cosa relacionada con Intlayer, usamos esta información para definir nuestra hoja de ruta y mejorar el producto.

      npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init
      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;
      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(),    tanstackStart({      router: {        routeFileIgnorePattern:          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",      },    }),    viteReact(),  ],});export default config;
      import {  createRootRouteWithContext,  HeadContent,  Scripts,} from "@tanstack/react-router";import { defaultLocale, getHTMLTextDir } from "intlayer";import { type ReactNode } from "react";import { IntlayerProvider } from "react-intlayer";import { Route as LocaleRoute } from "./{-$locale}/route";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>  );}
      <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)}" />
      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,});
      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;
      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"]}    />  );};
      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;};
      import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";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>  );}
      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>              {/* Configuración regional - p. ej. FR */}              {localeEl}            </span>            <span>              {/* Idioma en su propia configuración regional - p. ej. Français */}              {getLocaleName(localeEl, locale)}            </span>            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>              {/* Idioma en la configuración regional actual - p. ej. Francés con la configuración regional actual establecida en 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>  );};
      function RootDocument({ children }: { children: ReactNode }) {  const params = LocaleRoute.useParams();  const locale = params?.locale ?? defaultLocale;  return (    <html dir={getHTMLTextDir(locale)} lang={locale}>      {/* ... */}    </html>  );}
      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, intlayerProxy } from "vite-intlayer";export default defineConfig({  plugins: [    intlayerProxy(), // El proxy debe colocarse antes que el servidor si utilizas Nitro    nitro(),    intlayer(),    tanstackStart({      router: {        routeFileIgnorePattern:          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",      },    }),    viteReact(),  ],});
      import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";export const Route = createFileRoute("/{-$locale}/")({  component: RouteComponent,  head: ({ params }) => {    const { locale } = params;    const path = "/"; // The path for this route    const metaContent = getIntlayer("app", locale);    return {      links: [        // Canonical link: Points to the current localized page        { rel: "canonical", href: getLocalizedUrl(path, locale) },        // Hreflang: Tell Google about all localized versions        ...localeMap(({ locale: mapLocale }) => ({          rel: "alternate",          hrefLang: mapLocale,          href: getLocalizedUrl(path, mapLocale),        })),        // x-default: For users in unmatched languages        // Define the default fallback locale (usually your primary language)        {          rel: "alternate",          hrefLang: "x-default",          href: getLocalizedUrl(path, defaultLocale),        },      ],      meta: [        { title: metaContent.title },        { name: "description", content: metaContent.meta.description },      ],    };  },});
      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({    // Obtener la cookie de la solicitud (por defecto: 'INTLAYER_LOCALE')    getCookie: (name) => {      const cookieString = getRequestHeader("cookie");      return getCookie(name, cookieString);    },    // Obtener el encabezado de la solicitud (por defecto: 'x-intlayer-locale')    // Respaldo mediante negociación Accept-Language    getHeader: (name) => getRequestHeader(name),  });  // Recuperar algún contenido usando getIntlayer()  const content = getIntlayer("app", locale);  return { locale, content };});
      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 archivosexport const Route = createFileRoute("/{-$locale}/404")({  component: NotFoundComponent,});// Exportado por separado para que pueda reutilizarse en notFoundComponent y rutas catch-allexport function NotFoundComponent() {  return (    <div>      <h1>404</h1>    </div>  );}
      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,});
      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 errorexport const Route = createFileRoute("/{-$locale}/$")({  component: NotFoundComponent,});
      npx intlayer extract
      import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Agrega el plugin del compilador ],});
      npm run build # O npm run dev
      import { localeFlatMap } from "intlayer";// ... otras importacionesexport 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,    }),  ],});
      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" },        });      },    },  },});
      {  // ... tus configuraciones existentes  include: [    // ... tus inclusiones existentes    ".intlayer/**/*.ts", // Incluir los tipos autogenerados  ],}
      # Ignorar los archivos generados por Intlayer.intlayer