Dashboard

Cambio lingua

Come configurare e passare da una lingua all’altra nella tua app Next.js

La funzione di cambio lingua consente agli utenti di impostare la lingua/locale preferita per i contenuti della tua applicazione. GT Next offre diversi approcci, dal semplice cambio via codice al routing completo basato su URL con middleware.

Metodi disponibili

Uso dell’hook useSetLocale

L’hook useSetLocale è un hook client-side che consente di cambiare la lingua della tua app:

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

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

  return <button onClick={() => setLocale('en')}>Imposta lingua</button>;
}

È sufficiente passare la locale desiderata come argomento alla funzione restituita dall’hook.

Utilizzo del componente <LocaleSelector>

Il componente <LocaleSelector> fornisce un menu a discesa pronto all’uso che mostra automaticamente tutte le lingue/locale configurate:

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

export default function MyComponent() {
  return <LocaleSelector />;
}

Questo componente:

  • Mostra tutte le lingue/locale configurate per il tuo progetto
  • Visualizza le lingue/locale con i loro nomi nella lingua originale
  • Gestisce la logica di cambio lingua
  • Mantiene lo stato della selezione attuale

Uso dell’hook useLocaleSelector

Se vuoi creare un componente personalizzato per la selezione della lingua/locale, usa useLocaleSelector:

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

function CustomLocaleSelector() {
  const { 
    locale,              // Impostazione locale attiva (es. 'en', 'es')
    locales,             // Elenco delle impostazioni locali supportate dal progetto ['en', 'es', 'fr']
    setLocale,           // Funzione per cambiare l'impostazione locale: setLocale('es')
    getLocaleProperties  // Funzione per ottenere le informazioni di visualizzazione per un'impostazione 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.nativeNameWithRegionCode} {/* es. "English (US)", "Español (ES)" */}
          </option>
        );
      })}
    </select>
  );
}

Cambio lingua basato sull’URL

Per la SEO e una migliore UX, puoi includere il locale negli URL utilizzando il routing middleware. Trovi più informazioni su questo approccio nella Guida al middleware:

/en/products  → Pagina prodotti in inglese  
/es/products  → Pagina prodotti in spagnolo
/fr/products  → Pagina prodotti in francese

Questo approccio offre vantaggi SEO, collegamenti diretti alle versioni linguistiche e link localizzati facilmente condivisibili.

Avvertenze importanti

Solo Client Components

Tutti gli hook e i componenti per il cambio della lingua devono essere usati nei Client Components contrassegnati con 'use client':

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

function LanguageSwitcher() {
  const setLocale = useSetLocale();
  // ... logica del componente
}

Requisito per GTProvider

I componenti per la modifica della lingua devono essere utilizzati all'interno di <GTProvider>:

// ✅ Corretto
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ Errato - al di fuori del provider
<LanguageSwitcher />

Prossimi passi

Come valuti questa guida?

In questa pagina

Metodi disponibili
Uso dell’hook useSetLocale
Utilizzo del componente <LocaleSelector>
Uso dell’hook useLocaleSelector
Cambio lingua basato sull’URL
Avvertenze importanti
Solo Client Components
Requisito per GTProvider
Prossimi passi
Cambio lingua