El cambio de idioma permite que los usuarios seleccionen su locale preferido para el contenido de tu aplicación. GT Next ofrece varios enfoques, desde un cambio programático simple hasta un enrutamiento completo basado en URL con middleware.

Métodos disponibles

• Programático: hook useSetLocale para controles personalizados
• Interfaz prediseñada: componente <LocaleSelector> con menú desplegable
• Interfaz personalizada: hook useLocaleSelector para crear selectores personalizados
• Basado en URL: Enrutamiento con middleware para el locale en rutas de URL

Uso del hook useSetLocale

El hook useSetLocale es un hook del lado del cliente que te permite cambiar el idioma de tu aplicación:

import { useSetLocale } from 'gt-next/client';

export default function MyComponent() {
  const setLocale = useSetLocale();

  return <button onClick={() => setLocale('en')}>Establecer idioma</button>;
}

Basta con proporcionar el locale al que quieres cambiar como argumento de la función que devuelve el hook.

Uso del componente <LocaleSelector>

El componente <LocaleSelector> proporciona 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, automáticamente:

• Muestra todas las locales configuradas para tu proyecto
• Muestra las locales con sus nombres en su 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 locales personalizado, usa useLocaleSelector:

import { useLocaleSelector } from 'gt-next/client';

function CustomLocaleSelector() {
  const { 
    locale,              // Idioma activo actual (p. ej., 'en', 'es')
    locales,             // Array de idiomas que soporta tu proyecto ['en', 'es', 'fr']
    setLocale,           // Función para cambiar el idioma: setLocale('es')
    getLocaleProperties  // Función para obtener información de visualización de un idioma
  } = 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 SEO y una mejor experiencia de usuario, 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és

Este enfoque ofrece ventajas de SEO, enlaces directos a las versiones por idioma y enlaces localizados fáciles de compartir.

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 de cambio de idioma deben utilizarse dentro de un <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:
  • useSetLocale Hook
  • <LocaleSelector> Component