Haz tu pregunta y obtén un resumen del documento referenciando esta página y el proveedor AI de tu elección
Al integrar el servidor MCP Intlayer a tu asistente de IA, puedes recuperar todos los documentos directamente desde ChatGPT, DeepSeek, Cursor, VSCode, etc.
Ver la documentación del servidor MCPEl 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
Guía paso a paso para configurar Intlayer en una aplicación Vite y React
Paso 1: Instalar dependencias
Instala los paquetes necesarios usando npm:
Copiar el código al portapapeles
npm install intlayer react-intlayernpm install vite-intlayer --save-dev
intlayer
El paquete principal que proporciona herramientas de internacionalización para la gestión de configuración, traducción, declaración de contenido, transpile y comandos CLI.
react-intlayer El paquete que integra Intlayer con aplicaciones React. Proporciona proveedores de contexto y hooks para la internacionalización en React.
vite-intlayer Incluye el plugin de Vite para integrar Intlayer con el empaquetador Vite, así como middleware para detectar el idioma preferido del usuario, gestionar cookies y manejar redirecciones de URL.
Paso 2: Configuración de tu proyecto
Crea un archivo de configuración para configurar los idiomas de tu aplicación:
Copiar el código al portapapeles
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // Tus otros idiomas ], defaultLocale: Locales.ENGLISH, },};export default config;
A través de este archivo de configuración, puedes configurar URLs localizadas, redirección de middleware, nombres de cookies, la ubicación y extensión de tus declaraciones de contenido, desactivar los registros de Intlayer en la consola, y más. Para una lista completa de los parámetros disponibles, consulta la documentación de configuración.
Paso 3: Integra Intlayer en tu configuración de Vite
Agrega el plugin intlayer en tu configuración.
Copiar el código al portapapeles
import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayerPlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({ plugins: [react(), intlayerPlugin()],});
El plugin intlayerPlugin() de Vite se utiliza para integrar Intlayer con Vite. Garantiza la construcción de archivos de declaración de contenido y los supervisa en modo de desarrollo. Define variables de entorno de Intlayer dentro de la aplicación Vite. Además, proporciona alias para optimizar el rendimiento.
Paso 4: Declara Tu Contenido
Crea y administra tus declaraciones de contenido para almacenar traducciones:
Copiar el código al portapapeles
import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = { key: "app", content: { viteLogo: t({ en: "Vite logo", fr: "Logo Vite", es: "Logo Vite", }), reactLogo: t({ en: "React logo", fr: "Logo React", es: "Logo React", }), title: "Vite + React", count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es ", }), edit: t<ReactNode>({ en: ( <> Edita <code>src/App.tsx</code> y guarda para probar HMR </> ), fr: ( <> Éditez <code>src/App.tsx</code> et enregistrez pour tester HMR </> ), es: ( <> Edita <code>src/App.tsx</code> y guarda para probar HMR </> ), }), readTheDocs: t({ en: "Haz clic en los logotipos de Vite y React para obtener más información", fr: "Cliquez sur les logos Vite et React pour en savoir plus", es: "Haz clic en los logotipos de Vite y React para obtener más información", }), },} satisfies Dictionary;export default appContent;
Sus declaraciones de contenido pueden definirse en cualquier lugar de su aplicación tan pronto como se incluyan en el directorio contentDir (por defecto, ./src). Y coincidan con la extensión del archivo de declaración de contenido (por defecto, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).
Para más detalles, consulte la documentación de declaración de contenido.
Si su archivo de contenido incluye código TSX, debería considerar importar import React from "react"; en su archivo de contenido.
Paso 5: Utilice Intlayer en su Código
Acceda a sus diccionarios de contenido en toda su aplicación:
Copiar el código al portapapeles
import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); const content = useIntlayer("app"); return ( <> <div> <a href="https://vitejs.dev" target="_blank"> <img src={viteLogo} className="logo" alt={content.viteLogo.value} /> </a> <a href="https://react.dev" target="_blank"> <img src={reactLogo} className="logo react" alt={content.reactLogo.value} /> </a> </div> <h1>{content.title}</h1> <div className="card"> <button onClick={() => setCount((count) => count + 1)}> {content.count} {count} </button> <p>{content.edit}</p> </div> <p className="read-the-docs">{content.readTheDocs}</p> </> );};const App: FC = () => ( <IntlayerProvider> <AppContent /> </IntlayerProvider>);export default App;
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í:
jsxCopiar códigoCopiar el código al portapapeles
<img src={content.image.src.value} alt={content.image.value} />
Para aprender más sobre el hook useIntlayer, consulta la documentación.
(Opcional) Paso 6: Cambiar el idioma de tu contenido
Para cambiar el idioma de tu contenido, puedes usar la función setLocale proporcionada por el hook useLocale. Esta función te permite establecer la configuración regional de la aplicación y actualizar el contenido en consecuencia.
Copiar el código al portapapeles
import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => { const { setLocale } = useLocale(); return ( <button onClick={() => setLocale(Locales.English)}> Cambiar idioma a inglés </button> );};
Para aprender más sobre el hook useLocale, consulte la documentación.
(Opcional) Paso 7: Agregar enrutamiento localizado a su aplicación
El propósito de este paso es crear rutas únicas para cada idioma. Esto es útil para SEO y URLs amigables con SEO. Ejemplo:
Copiar el código al portapapeles
- https://example.com/about- https://example.com/es/about- https://example.com/fr/about
Por defecto, las rutas no tienen prefijo para la configuración regional predeterminada. Si desea agregar un prefijo para la configuración regional predeterminada, puede establecer la opción middleware.prefixDefault en true en su configuración. Consulte la documentación de configuración para obtener más información.
Para agregar enrutamiento localizado a su aplicación, puede crear un componente LocaleRouter que envuelva las rutas de su aplicación y gestione el enrutamiento basado en la configuración regional. Aquí hay un ejemplo usando React Router:
Copiar el código al portapapeles
// Importando las dependencias y funciones necesariasimport { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Funciones y tipos utilitarios de 'intlayer'import type { FC, PropsWithChildren } from "react"; // Tipos de React para componentes funcionales y propsimport { IntlayerProvider } from "react-intlayer"; // Proveedor para el contexto de internacionalizaciónimport { BrowserRouter, Routes, Route, Navigate, useLocation,} from "react-router-dom"; // Componentes del router para gestionar la navegación// Desestructurando la configuración de Intlayerconst { internationalization, middleware } = configuration;const { locales, defaultLocale } = internationalization;/** * Un componente que maneja la localización y envuelve a los hijos con el contexto de locale apropiado. * Gestiona la detección y validación del locale basado en la URL. */const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({ children, locale,}) => { const { pathname, search } = useLocation(); // Obtener la ruta URL actual // Determinar la configuración regional actual, usando la predeterminada si no se proporciona const currentLocale = locale ?? defaultLocale; // Eliminar el prefijo de la configuración regional de la ruta para construir una ruta base const pathWithoutLocale = getPathWithoutLocale( pathname // Ruta URL actual ); /** * Si middleware.prefixDefault es true, la configuración regional predeterminada siempre debe tener prefijo. */ if (middleware.prefixDefault) { // Validar la configuración regional if (!locale || !locales.includes(locale)) { // Redirigir a la configuración regional predeterminada con la ruta actualizada return ( <Navigate to={`/${defaultLocale}/${pathWithoutLocale}${search}`} replace // Reemplaza la entrada actual del historial con la nueva /> ); } // Envuelve los hijos con IntlayerProvider y establece la configuración regional actual return ( <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider> ); } else { /** * Cuando middleware.prefixDefault es falso, la configuración regional predeterminada no tiene prefijo. * Asegúrate de que la configuración regional actual sea válida y no sea la predeterminada. */ if ( currentLocale.toString() !== defaultLocale.toString() && !locales .filter( (locale) => locale.toString() !== defaultLocale.toString() // Excluir la configuración regional predeterminada ) .includes(currentLocale) // Verifica si la configuración regional actual está en la lista de configuraciones regionales válidas ) { // Redirige a la ruta sin el prefijo de configuración regional return <Navigate to={`${pathWithoutLocale}${search}`} replace />; } // Envuelve los hijos con IntlayerProvider y establece la configuración regional actual return ( <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider> ); }};/** * Un componente de enrutador que configura rutas específicas por configuración regional. * Utiliza React Router para gestionar la navegación y renderizar componentes localizados. */export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => ( <BrowserRouter> <Routes> {locales .filter( (locale) => middleware.prefixDefault || locale !== defaultLocale ) .map((locale) => ( <Route // Patrón de ruta para capturar la localidad (por ejemplo, /en/, /fr/) y coincidir con todas las rutas subsecuentes path={`/${locale}/*`} key={locale} element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Envuelve los hijos con la gestión de la localidad /> ))} { // Si el prefijo para la localidad por defecto está deshabilitado, renderiza los hijos directamente en la ruta raíz !middleware.prefixDefault && ( <Route path="*" element={ <AppLocalized locale={defaultLocale}>{children}</AppLocalized> } // Envuelve los hijos con la gestión de la localidad /> ) } </Routes> </BrowserRouter>);
Luego, puedes usar el componente LocaleRouter en tu aplicación:
Copiar el código al portapapeles
import { LocaleRouter } from "./components/LocaleRouter";import type { FC } from "react";// ... Tu componente AppContentconst App: FC = () => ( <LocaleRouter> <AppContent /> </LocaleRouter>);
Paralelamente, también puedes usar el intlayerMiddlewarePlugin para agregar 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 correspondiente. Si no se especifica ninguna configuración regional, el plugin determinará la configuración regional más adecuada basándose en las preferencias de idioma del navegador del usuario. Si no se detecta ninguna configuración regional, redirigirá a la configuración regional predeterminada.
Copiar el código al portapapeles
import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayerPlugin, intlayerMiddlewarePlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({ plugins: [react(), intlayerPlugin(), intlayerMiddlewarePlugin()],});
(Opcional) Paso 8: Cambiar la URL cuando cambia la configuración regional
Para cambiar la URL cuando cambia la configuración regional, puedes usar la propiedad onLocaleChange proporcionada por el hook useLocale. Paralelamente, puedes usar los hooks useLocation y useNavigate de react-router-dom para actualizar la ruta de la URL.
Copiar el código al portapapeles
import { useLocation, useNavigate } from "react-router-dom";import { Locales, getHTMLTextDir, getLocaleName, getLocalizedUrl,} from "intlayer";import { useLocale } from "react-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => { const { pathname, search } = useLocation(); // Obtener la ruta actual de la URL. Ejemplo: /fr/about?foo=bar const navigate = useNavigate(); const { locale, availableLocales, setLocale } = useLocale({ onLocaleChange: (locale) => { // Construir la URL con la configuración regional actualizada // Ejemplo: /es/about?foo=bar const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale); // Actualizar la ruta de la URL navigate(pathWithLocale); }, }); return ( <div> <button popoverTarget="localePopover">{getLocaleName(locale)}</button> <div id="localePopover" popover="auto"> {availableLocales.map((localeItem) => ( <a href={getLocalizedUrl(location.pathname, localeItem)} hrefLang={localeItem} aria-current={locale === localeItem ? "page" : undefined} onClick={(e) => { e.preventDefault(); setLocale(localeItem); }} key={localeItem} > <span> {/* Local - p.ej. FR */} {localeItem} </span> <span> {/* Idioma en su propia localización - p.ej. Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Idioma en la localización actual - p.ej. Francés con la localización actual configurada en Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Idioma en inglés - p.ej. French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </a> ))} </div> </div> );};
Referencias de la documentación:
A continuación se muestra el Paso 9 actualizado con explicaciones añadidas y ejemplos de código refinados:
(Opcional) Paso 9: Cambiar los atributos de idioma y dirección en el HTML
Cuando tu aplicación soporta múltiples idiomas, es crucial actualizar los atributos lang y dir de la etiqueta <html> para que coincidan con la configuración regional actual. Hacer esto garantiza:
- Accesibilidad: Los lectores de pantalla y las tecnologías de asistencia dependen del atributo lang correcto para pronunciar e interpretar el contenido con precisión.
- Renderizado de texto: El atributo dir (dirección) asegura que el texto se muestre en el orden adecuado (por ejemplo, de izquierda a derecha para inglés, de derecha a izquierda para árabe o hebreo), lo cual es esencial para la legibilidad.
- SEO: Los motores de búsqueda utilizan el atributo lang para determinar el idioma de tu página, ayudando a mostrar el contenido localizado correcto en los resultados de búsqueda.
Al actualizar estos atributos dinámicamente cuando cambia la configuración regional, garantizas una experiencia coherente y accesible para los usuarios en todos los idiomas compatibles.
Implementación del Hook
Crea un hook personalizado para gestionar los atributos HTML. El hook escucha los cambios de configuración regional y actualiza los atributos en consecuencia:
Copiar el código al portapapeles
import { useEffect } from "react";import { useLocale } from "react-intlayer";import { getHTMLTextDir } from "intlayer";/** * Actualiza los atributos `lang` y `dir` del elemento HTML <html> según la configuración regional actual. * - `lang`: Informa a los navegadores y motores de búsqueda sobre el idioma de la página. * - `dir`: Asegura el orden correcto de lectura (por ejemplo, 'ltr' para inglés, 'rtl' para árabe). * * Esta actualización dinámica es esencial para el renderizado correcto del texto, accesibilidad y SEO. */export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { // Actualiza el atributo de idioma al locale actual. document.documentElement.lang = locale; // Establece la dirección del texto según el locale actual. document.documentElement.dir = getHTMLTextDir(locale); }, [locale]);};
Uso del Hook en Tu Aplicación
Integra el hook en tu componente principal para que los atributos HTML se actualicen cada vez que cambie la configuración regional:
Copiar el código al portapapeles
import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";import "./App.css";const AppContent: FC = () => { // Aplica el hook para actualizar los atributos lang y dir de la etiqueta <html> según la configuración regional. useI18nHTMLAttributes(); // ... Resto de tu componente};const App: FC = () => ( <IntlayerProvider> <AppContent /> </IntlayerProvider>);export default App;
Al aplicar estos cambios, tu aplicación:
- Asegurará que el atributo language (lang) refleje correctamente la configuración regional actual, lo cual es importante para SEO y el comportamiento del navegador.
- Ajustará la dirección del texto (dir) según la configuración regional, mejorando la legibilidad y usabilidad para idiomas con diferentes órdenes de lectura.
- Proporcionará una experiencia más accesible, ya que las tecnologías de asistencia dependen de estos atributos para funcionar de manera óptima.
(Opcional) Paso 10: Crear un Componente de Enlace Localizado
Para asegurar que la navegación de su aplicación respete la configuración regional actual, puede crear un componente personalizado Link. Este componente antepone automáticamente a las URLs internas el idioma actual. Por ejemplo, cuando un usuario francófono hace clic en un enlace a la página "Acerca de", es redirigido a /fr/about en lugar de /about.
Este comportamiento es útil por varias razones:
- SEO y experiencia del usuario: Las URLs localizadas ayudan a los motores de búsqueda a indexar correctamente las páginas específicas por idioma y proporcionan a los usuarios contenido en su idioma preferido.
- Consistencia: Al usar un enlace localizado en toda su aplicación, garantiza que la navegación se mantenga dentro de la configuración regional actual, evitando cambios inesperados de idioma.
- Mantenibilidad: Centralizar la lógica de localización en un solo componente simplifica la gestión de URLs, haciendo que tu base de código sea más fácil de mantener y extender a medida que tu aplicación crece.
A continuación se muestra la implementación de un componente Link localizado en TypeScript:
Copiar el código al portapapeles
import { getLocalizedUrl } from "intlayer";import { forwardRef, type DetailedHTMLProps, type AnchorHTMLAttributes,} from "react";import { useLocale } from "react-intlayer";export interface LinkProps extends DetailedHTMLProps< AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement > {}/** * Función utilitaria para verificar si una URL dada es externa. * Si la URL comienza con http:// o https://, se considera externa. */export const checkIsExternalLink = (href?: string): boolean => /^https?:\/\//.test(href ?? "");/** * Un componente Link personalizado que adapta el atributo href según la configuración regional actual. * Para enlaces internos, utiliza `getLocalizedUrl` para anteponer la configuración regional a la URL (por ejemplo, /fr/about). * Esto asegura que la navegación se mantenga dentro del mismo contexto regional. */export const Link = forwardRef<HTMLAnchorElement, LinkProps>( ({ href, children, ...props }, ref) => { const { locale } = useLocale(); const isExternalLink = checkIsExternalLink(href); // Si el enlace es interno y se proporciona un href válido, obtener la URL localizada. const hrefI18n = href && !isExternalLink ? getLocalizedUrl(href, locale) : href; return ( <a href={hrefI18n} ref={ref} {...props}> {children} </a> ); });Link.displayName = "Link";
Cómo Funciona
Detección de Enlaces Externos:
La función auxiliar checkIsExternalLink determina si una URL es externa. Los enlaces externos se dejan sin cambios porque no necesitan localización.Obtención del Locale Actual:
El hook useLocale proporciona el locale actual (por ejemplo, fr para francés).Localización de la URL:
Para enlaces internos (es decir, no externos), se utiliza getLocalizedUrl para prefijar automáticamente la URL con el locale actual. Esto significa que si tu usuario está en francés, pasar /about como href se transformará en /fr/about.Retorno del Enlace:
El componente devuelve un elemento <a> con la URL localizada, asegurando que la navegación sea coherente con la configuración regional.
Al integrar este componente Link en toda su aplicación, mantiene una experiencia de usuario coherente y consciente del idioma, además de beneficiarse de una mejor SEO y usabilidad.
Configurar TypeScript
Intlayer utiliza la ampliación de módulos para aprovechar las ventajas de TypeScript y fortalecer su base de código.
Asegúrese de que su configuración de TypeScript incluya los tipos generados automáticamente.
Copiar el código al portapapeles
{ // ... Sus configuraciones existentes de TypeScript "include": [ // ... Tus configuraciones existentes de TypeScript ".intlayer/**/*.ts", // Incluir los tipos generados automáticamente ],}
Configuración de Git
Se recomienda ignorar los archivos generados por Intlayer. Esto te permite evitar comprometerlos en tu repositorio Git.
Para hacerlo, puedes agregar las siguientes instrucciones a tu archivo .gitignore:
Copiar el código al portapapeles
# Ignorar los archivos generados por Intlayer.intlayer
Extensión para VS Code
Para mejorar tu experiencia de desarrollo con Intlayer, puedes instalar la Extensión oficial de Intlayer para VS Code.
Instalar desde el Marketplace de VS Code
Esta extensión ofrece:
- Autocompletado para las claves de traducción.
- Detección de errores en tiempo real para traducciones faltantes.
- Vistas previas en línea del contenido traducido.
- Acciones rápidas para crear y actualizar traducciones fácilmente.
Para más detalles sobre cómo usar la extensión, consulta la documentación de la extensión Intlayer para VS Code.
Ir más allá
Para ir más allá, puedes implementar el editor visual o externalizar tu contenido usando el CMS.
Historial del documento
- 5.5.10 - 2025-06-29: Historial inicial