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
- "Actualizar el uso de la API useIntlayer de Solid para el acceso directo a las propiedades"v8.9.04/5/2026
- "Añadido para Tanstack Start Solid.js"v8.5.125/3/2026
El contenido de esta página ha sido traducido con una IA.
Ver la última versión del contenido original en inglésSi tienes una idea para mejorar esta documentación, no dudes en contribuir enviando una pull request en GitHub.
Enlace de GitHub a la documentaciónCopiar el Markdown del documento a la portapapeles
Traduzca su sitio web Tanstack Start con Solid.js 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 Solid.js, enrutamiento consciente de la localización, soporte de TypeScript y prácticas de desarrollo modernas.
¿Por qué Intlayer en lugar de alternativas?
En comparación con soluciones principales como react-i18next o i18next, Intlayer es una solución que viene con optimizaciones integradas como:
Intlayer está optimizado para funcionar perfectamente con TanStack Start y Solid al ofrecer enrutamiento multilingüe, mapa del sitio y todas las funciones necesarias para escalar la internacionalización (i18n).
En lugar de cargar archivos JSON masivos en sus páginas, cargue solo el contenido necesario. Intlayer ayuda a reducir el tamaño de su bundle y de sus páginas hasta en un 50%.
Determinar el alcance del contenido de su aplicación facilita el mantenimiento para aplicaciones a gran escala. Puede duplicar o eliminar una sola carpeta de funciones sin la carga mental de revisar todo el código base de contenido. Además, Intlayer está completamente escrito para garantizar la precisión de su contenido.
La ubicación conjunta de contenido reduce el contexto necesario para los modelos de lenguajes grandes (LLM). Intlayer también viene con un conjunto de herramientas, como una CLI para comprobar si faltan traducciones,LSP, MCP y agent skills, para que la experiencia del desarrollador (DX) sea aún más fluida para los agentes de IA.
Utilice la automatización para traducir su canal de CI/CD utilizando el LLM de su elección al costo de su proveedor de IA. Intlayer también ofrece un compilador para automatizar la extracción de contenido, así como una plataforma web para ayudar a traducir en segundo plano.
La conexión de archivos JSON masivos a componentes puede provocar problemas de rendimiento y reactividad. Intlayer optimiza la carga de su contenido en el momento de la compilación.
Más que una simple solución i18n, Intlayer proporciona un [editor visual] autohospedado(/es/doc/concept/editor) y un CMS completo para ayudarle a administrar su contenido multilingüe en tiempo real, lo que facilita la colaboración con traductores, redactores y otros miembros del equipo. El contenido se puede almacenar de forma local y/o remota.
Guía paso a paso para configurar Intlayer en una aplicación Tanstack Start
Ver Plantilla de aplicación en GitHub.
Crear el proyecto
Comience creando un nuevo proyecto TanStack Start siguiendo la guía Iniciar nuevo proyecto en el sitio web de TanStack Start.
Instalar los paquetes de Intlayer
Instale los paquetes necesarios utilizando su gestor de paquetes preferido:
bashCopiar códigoCopiar el código al portapapeles
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.
solid-intlayer El paquete que integra Intlayer con la aplicación Solid. Proporciona proveedores de contexto y hooks para la internacionalización de Solid.
vite-intlayer Incluye el plugin de Vite para integrar Intlayer con el bundler Vite, así como el middleware para detectar el idioma preferido del usuario, gestionar cookies y manejar la redirección de URL.
Configuración de su proyecto
Cree un archivo de configuración para configurar los idiomas de su aplicación:
intlayer.config.tsCopiar códigoCopiar el código al portapapeles
A través de este archivo de configuración, puede configurar URLs localizadas, redirección de middleware, nombres de cookies, la ubicación y extensión de sus declaraciones de contenido, desactivar los registros de Intlayer en la consola, y más. Para una lista completa de los parámetros disponibles, consulte la documentación de configuración.
Integrar Intlayer en su configuración de Vite
Añada el plugin de intlayer en su configuración:
vite.config.tsCopiar códigoCopiar el código al portapapeles
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 monitoriza en modo de desarrollo. Define las variables de entorno de Intlayer dentro de la aplicación Vite. Además, proporciona alias para optimizar el rendimiento.Crear el diseño raíz
Configure su diseño raíz para soportar la internacionalización utilizando
useParamspara detectar el idioma actual y estableciendo los atributoslangydiren la etiquetahtml.src/routes/__root.tsxCopiar códigoCopiar el código al portapapeles
Crear el diseño de idioma
Cree un diseño que maneje el prefijo de idioma y realice la validación. Este diseño asegurará que solo se procesen idiomas válidos.
Este paso es opcional si no necesita validar el prefijo de idioma a nivel de ruta.
src/routes/{-$locale}/route.tsxCopiar códigoCopiar el código al portapapeles
Aquí,
{-$locale}es un parámetro de ruta dinámico que se reemplaza con el idioma actual. Esta notación hace que el hueco sea opcional, permitiendo que funcione con modos de enrutamiento como'prefix-no-default', etc.Tenga en cuenta que este hueco puede causar problemas si utiliza múltiples segmentos dinámicos en la misma ruta (por ejemplo,
/{-$locale}/otro-camino/$otroCaminoDinamico/...). Para el modo'prefix-all', puede preferir cambiar el hueco a$localeen su lugar. Para el modo'no-prefix'o'search-params', puede eliminar el hueco por completo.Declarar su contenido
Cree y gestione sus declaraciones de contenido para almacenar traducciones:
src/contents/page.content.tsCopiar códigoCopiar el código al portapapeles
Sus declaraciones de contenido pueden definirse en cualquier lugar de su aplicación siempre que estén incluidas en el directorio
contentDir(por defecto,./app). Y coincidan con la extensión de archivo de declaración de contenido (por defecto,.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).Para más detalles, consulte la documentación de declaración de contenido.
Utilizar componentes y hooks conscientes del idioma
Cree un componente
LocalizedLinkpara una navegación consciente del idioma:src/components/LocalizedLink.tsxCopiar códigoCopiar el código al portapapeles
Este componente tiene dos objetivos:
- Eliminar el prefijo innecesario
{-$locale}de la URL. - Inyectar el parámetro de idioma en la URL para asegurar que el usuario sea redirigido directamente a la ruta localizada.
Luego podemos crear un hook
useLocalizedNavigatepara la navegación programática:src/hooks/useLocalizedNavigate.tsxCopiar códigoCopiar el código al portapapeles
- Eliminar el prefijo innecesario
Utilizar Intlayer en sus páginas
Acceda a sus diccionarios de contenido en toda su aplicación:
Página de inicio localizada
src/routes/{-$locale}/index.tsxCopiar códigoCopiar el código al portapapeles
Si deseas usar tu contenido en un atributo de tipo
string, comoalt,title,href,aria-label, etc., debes llamar al valor de la función, así:htmlCopiar códigoCopiar el código al portapapeles
En Solid,
useIntlayerdevuelve contenido reactivo (por ejemplo,content). Puedes acceder a sus propiedades directamente.Para saber más sobre el hook
useIntlayer, consulte la documentación.Crear un componente selector de idioma
Cree un componente para permitir a los usuarios cambiar de idioma:
src/components/LocaleSwitcher.tsxCopiar códigoCopiar el código al portapapeles
En Solid,
localedeuseLocalees un signal accessor. Uselocale()(con paréntesis) para leer su valor actual de forma reactiva.Para saber más sobre el hook
useLocale, consulte la documentación.Gestión de atributos HTML
Como vimos en el Paso 5, puede gestionar los atributos
langydirde la etiquetahtmlutilizandouseParamsen su componente raíz. Esto asegura que se establezcan los atributos correctos tanto en el servidor como en el cliente.src/routes/__root.tsxCopiar códigoCopiar el código al portapapeles
Añadir middleware
También puede utilizar
intlayerProxypara añadir enrutamiento del lado del servidor a su aplicación. Este plugin detectará automáticamente el idioma actual basándose en la URL y establecerá la cookie de idioma adecuada. Si no se especifica ningún idioma, el plugin determinará el idioma más apropiado basándose en las preferencias de idioma del navegador del usuario. Si no se detecta ningún idioma, redirigirá al idioma predeterminado.Tenga en cuenta que para utilizar
intlayerProxyen producción, necesita cambiar el paquetevite-intlayerdedevDependenciesadependencies.vite.config.tsCopiar códigoCopiar el código al portapapeles
Internacionalizar sus metadatos
También puede utilizar la función
getIntlayerpara acceder a sus diccionarios de contenido dentro del cargadorheadpara metadatos conscientes de la localización:src/routes/{-$locale}/index.tsxCopiar códigoCopiar el código al portapapeles
Recuperar el idioma en sus acciones de servidor
Es posible que desee acceder al idioma actual desde sus acciones de servidor o endpoints de API. Puede hacerlo utilizando el ayudante
getLocaledeintlayer.Aquí tiene un ejemplo utilizando las funciones de servidor de TanStack Start:
src/routes/{-$locale}/index.tsxCopiar códigoCopiar el código al portapapeles
Gestionar páginas no encontradas
Cuando un usuario visita una página inexistente, puede mostrar una página 404 personalizada y el prefijo de idioma puede afectar a la forma en que se activa la página no encontrada.
Entendiendo el manejo de 404 de TanStack Router con prefijos de idioma
En TanStack Router, el manejo de páginas 404 con rutas localizadas requiere un enfoque de múltiples capas:
- Ruta 404 dedicada: Una ruta específica para mostrar la interfaz de usuario 404.
- Validación a nivel de ruta: Valida los prefijos de idioma y redirige los inválidos a 404.
- Ruta catch-all: Captura cualquier ruta que no coincida dentro del segmento de idioma.
src/routes/{-$locale}/404.tsxCopiar códigoCopiar el código al portapapeles
src/routes/{-$locale}/route.tsxCopiar códigoCopiar el código al portapapeles
src/routes/{-$locale}/$.tsxCopiar códigoCopiar el código al portapapeles
Extraer el contenido de sus componentes
OpcionalSi tiene 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 sus componentes y extraer el contenido.
To set it up, you can add a
compilersection in yourintlayer.config.tsfile:intlayer.config.tsCopiar códigoCopiar el código al portapapeles
import { type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { // ... Resto de su 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 del componente en el disco. Así la transformación será permanente, y el compilador omitirá la transformación para el siguiente proceso. De esa manera, el compilador puede transformar la aplicación, y luego puede ser eliminado. * * - Si es `false`, el compilador inyectará la llamada a la función `useIntlayer()` en el código de la salida de construcción solamente, y mantendrá la base de código intacta. La transformación se hará solo en memoria. */ saveComponents: false, /** * Prefijo de clave de diccionario */ dictionaryKeyPrefix: "", }, }; export default config;Ejecute el extractor para transformar sus componentes y extraer el contenido
bashCopiar códigoCopiar el código al portapapeles
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=fry/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.tspara habilitar el prerrenderizado de tus rutas localizadas y deshabilitar la generación de sitemap predeterminada de TanStack Start.vite.config.tsCopiar códigoCopiar el código al portapapeles
Luego, crea una ruta
src/routes/sitemap[.]xml.tsque use la funcióngenerateSitemap:src/routes/sitemap[.]xml.tsCopiar códigoCopiar el código al portapapeles
Configurar TypeScript
Intlayer utiliza el aumento de módulos para aprovechar las ventajas de TypeScript y hacer que su base de código sea más robusta.
Asegúrese de que su configuración de TypeScript incluya los tipos autogenerados:
tsconfig.jsonCopiar códigoCopiar el código al portapapeles
Configuración de Git
Se recomienda ignorar los archivos generados por Intlayer. Esto le permite evitar subirlos a su repositorio Git.
Para hacerlo, puede añadir las siguientes instrucciones a su archivo .gitignore:
Copiar el código al portapapeles
Extensión de VS Code
Para mejorar su experiencia de desarrollo con Intlayer, puede instalar la Extensión oficial de Intlayer 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 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 utilizar la extensión, consulte la documentación de la extensión Intlayer VS Code.
Ir más allá
Para ir más allá, puede implementar el editor visual o externalizar su contenido utilizando el CMS.