Cambio de idioma
Cómo configurar y alternar entre idiomas en tu app de Next.js
El cambio de idioma permite a los usuarios establecer su locale preferido para el contenido de tu aplicación. GT Next ofrece varios enfoques, desde una conmutación programática sencilla hasta un enrutamiento completo basado en URL con middleware.
Métodos disponibles
- Programático: hook
useSetLocalepara controles personalizados - UI predefinida: componente
<LocaleSelector>con menú desplegable - UI personalizada: hook
useLocaleSelectorpara crear selectores personalizados - Basado en URL: enrutamiento con middleware para el locale en las rutas de la URL
Uso del hook useSetLocale
El hook useSetLocale es un hook client-side que te permite cambiar el idioma de tu app:
import { useSetLocale } from 'gt-next/client';
export default function MyComponent() {
const setLocale = useSetLocale();
return <button onClick={() => setLocale('en')}>Establecer idioma</button>;
}Simplemente proporciona el locale al que quieras cambiar como argumento de la función que devuelve el hook.
Uso del componente <LocaleSelector>
El componente <LocaleSelector> ofrece un menú desplegable listo para usar que muestra automáticamente todos los locales configurados:
import { LocaleSelector } from 'gt-next/client';
export default function MyComponent() {
return <LocaleSelector />;
}Este componente, de forma automática:
- Muestra todas las locales configuradas para tu proyecto
- Muestra las locales con su name en el idioma nativo
- Gestiona la lógica de cambio
- Mantiene el estado de la selección actual
Uso del hook useLocaleSelector
Si quieres crear tu propio componente selector de locale personalizado, usa useLocaleSelector:
import { useLocaleSelector } from 'gt-next/client';
function CustomLocaleSelector() {
const {
locale, // Locale activo actual (p. ej., 'en', 'es')
locales, // Array de locales que soporta tu proyecto ['en', 'es', 'fr']
setLocale, // Función para cambiar el locale: setLocale('es')
getLocaleProperties // Función para obtener información de visualización de un locale
} = useLocaleSelector();
if (!locales?.length) return null;
return (
<select
value={locale || ''}
onChange={(e) => setLocale(e.target.value)}
>
{locales.map((loc) => {
const props = getLocaleProperties(loc);
return (
<option key={loc} value={loc}>
{props.nombreNativoConCódigoDeRegión} {/* p. ej., "English (US)", "Español (ES)" */}
</option>
);
})}
</select>
);
}Cambio de idioma basado en URL
Para el SEO y una mejor UX, puedes incluir el locale en tus URL mediante enrutamiento con middleware. Puedes encontrar más información sobre este enfoque en la Guía de middleware:
/en/products → Página de productos en inglés
/es/products → Página de productos en español
/fr/products → Página de productos en francésEste enfoque aporta ventajas de SEO, enlaces directos a las versiones en cada idioma y enlaces localizados compartibles.
Notas importantes
Solo componentes de cliente
Todos los hooks y componentes para cambiar el idioma deben usarse en componentes de cliente marcados con 'use client':
'use client';
import { useSetLocale } from 'gt-next/client';
function LanguageSwitcher() {
const setLocale = useSetLocale();
// ... lógica del componente
}Requisito de GTProvider
Los componentes para cambiar el idioma deben usarse dentro de <GTProvider>:
// ✅ Correcto
<GTProvider>
<LanguageSwitcher />
</GTProvider>
// ❌ Incorrecto - fuera del proveedor
<LanguageSwitcher />Próximos pasos
- Guía de middleware - Enrutamiento de idioma basado en URL
- Guía de contenido dinámico - Traducción de contenido en tiempo de ejecución
- Referencia de API:
¿Qué te parece esta guía?