GitHub

Language switching allows users to change their preferred locale for your application's content. GT Next provides several approaches from simple programmatic switching to full URL-based routing with middleware.

Available Methods

Programmatic: useSetLocale hook for custom controls
Pre-built UI: <LocaleSelector> component with dropdown
Custom UI: useLocaleSelector hook for building custom selectors
URL-based: Middleware routing for locale in URL paths

Using the `useSetLocale` hook

The useSetLocale hook is a client-side hook that allows you to change the language of your app:

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

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

  return <button onClick={() => setLocale('en')}>Set Locale</button>;
}

Simply provide the locale you want to change to as the argument to the function returned by the hook.

Using the `<LocaleSelector>` component

The <LocaleSelector> component provides a ready-to-use dropdown that automatically shows all configured locales:

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

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

This component automatically:

Shows all configured locales for your project
Displays locales in their native language names
Handles the switching logic
Maintains current selection state

Using the `useLocaleSelector` hook

If you want to build your own custom locale selector component, use useLocaleSelector:

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

function CustomLocaleSelector() {
  const { 
    locale,              // Current active locale (e.g., 'en', 'es')
    locales,             // Array of locales your project supports ['en', 'es', 'fr']
    setLocale,           // Function to change the locale: setLocale('es')
    getLocaleProperties  // Function to get display info for a 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} {/* e.g., "English (US)", "Español (ES)" */}
          </option>
        );
      })}
    </select>
  );
}

URL-based Language Switching

For SEO and better UX, you can include locale in your URLs using middleware routing. You can find more information about this approach in the Middleware Guide:

/en/products  → English products page  
/es/products  → Spanish products page
/fr/products  → French products page

This approach provides SEO benefits, direct links to language versions, and shareable localized links.

Important Notes

Client Components Only

All language switching hooks and components must be used in client components marked with 'use client':

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

function LanguageSwitcher() {
  const setLocale = useSetLocale();
  // ... component logic
}

GTProvider Requirement

Language switching components must be used within a <GTProvider>:

// ✅ Correct
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ Wrong - outside provider
<LanguageSwitcher />

Next Steps

Middleware Guide - URL-based language routing
Dynamic Content Guide - Runtime content translation
API References:
- useSetLocale Hook
- <LocaleSelector> Component

Available Methods

Programmatic: useSetLocale hook for custom controls
Pre-built UI: <LocaleSelector> component with dropdown
Custom UI: useLocaleSelector hook for building custom selectors
URL-based: Middleware routing for locale in URL paths

Using the `useSetLocale` hook

The useSetLocale hook is a client-side hook that allows you to change the language of your app:

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

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

  return <button onClick={() => setLocale('en')}>Set Locale</button>;
}

Simply provide the locale you want to change to as the argument to the function returned by the hook.

Using the `<LocaleSelector>` component

The <LocaleSelector> component provides a ready-to-use dropdown that automatically shows all configured locales:

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

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

This component automatically:

Shows all configured locales for your project
Displays locales in their native language names
Handles the switching logic
Maintains current selection state

Using the `useLocaleSelector` hook

If you want to build your own custom locale selector component, use useLocaleSelector:

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

function CustomLocaleSelector() {
  const { 
    locale,              // Current active locale (e.g., 'en', 'es')
    locales,             // Array of locales your project supports ['en', 'es', 'fr']
    setLocale,           // Function to change the locale: setLocale('es')
    getLocaleProperties  // Function to get display info for a 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} {/* e.g., "English (US)", "Español (ES)" */}
          </option>
        );
      })}
    </select>
  );
}

URL-based Language Switching

For SEO and better UX, you can include locale in your URLs using middleware routing. You can find more information about this approach in the Middleware Guide:

/en/products  → English products page  
/es/products  → Spanish products page
/fr/products  → French products page

This approach provides SEO benefits, direct links to language versions, and shareable localized links.

Important Notes

Client Components Only

All language switching hooks and components must be used in client components marked with 'use client':

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

function LanguageSwitcher() {
  const setLocale = useSetLocale();
  // ... component logic
}

GTProvider Requirement

Language switching components must be used within a <GTProvider>:

// ✅ Correct
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ Wrong - outside provider
<LanguageSwitcher />

Next Steps

Middleware Guide - URL-based language routing
Dynamic Content Guide - Runtime content translation
API References:
- useSetLocale Hook
- <LocaleSelector> Component

Available Methods

Programmatic: useSetLocale hook for custom controls
Pre-built UI: <LocaleSelector> component with dropdown
Custom UI: useLocaleSelector hook for building custom selectors
URL-based: Middleware routing for locale in URL paths

Using the `useSetLocale` hook

The useSetLocale hook is a client-side hook that allows you to change the language of your app:

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

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

  return <button onClick={() => setLocale('en')}>Set Locale</button>;
}

Simply provide the locale you want to change to as the argument to the function returned by the hook.

Using the `<LocaleSelector>` component

The <LocaleSelector> component provides a ready-to-use dropdown that automatically shows all configured locales:

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

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

This component automatically:

Shows all configured locales for your project
Displays locales in their native language names
Handles the switching logic
Maintains current selection state

Using the `useLocaleSelector` hook

If you want to build your own custom locale selector component, use useLocaleSelector:

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

function CustomLocaleSelector() {
  const { 
    locale,              // Current active locale (e.g., 'en', 'es')
    locales,             // Array of locales your project supports ['en', 'es', 'fr']
    setLocale,           // Function to change the locale: setLocale('es')
    getLocaleProperties  // Function to get display info for a 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} {/* e.g., "English (US)", "Español (ES)" */}
          </option>
        );
      })}
    </select>
  );
}

URL-based Language Switching

For SEO and better UX, you can include locale in your URLs using middleware routing. You can find more information about this approach in the Middleware Guide:

/en/products  → English products page  
/es/products  → Spanish products page
/fr/products  → French products page

This approach provides SEO benefits, direct links to language versions, and shareable localized links.

Important Notes

Client Components Only

All language switching hooks and components must be used in client components marked with 'use client':

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

function LanguageSwitcher() {
  const setLocale = useSetLocale();
  // ... component logic
}

GTProvider Requirement

Language switching components must be used within a <GTProvider>:

// ✅ Correct
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ Wrong - outside provider
<LanguageSwitcher />

Next Steps

Middleware Guide - URL-based language routing
Dynamic Content Guide - Runtime content translation
API References:
- useSetLocale Hook
- <LocaleSelector> Component

Changing Languages

Available Methods

Using the `useSetLocale` hook

Using the `<LocaleSelector>` component

Using the `useLocaleSelector` hook

URL-based Language Switching

Important Notes

Client Components Only

GTProvider Requirement

Next Steps

On this page

Changing Languages

Available Methods

Using the `useSetLocale` hook

Using the `<LocaleSelector>` component

Using the `useLocaleSelector` hook

URL-based Language Switching

Important Notes

Client Components Only

GTProvider Requirement

Next Steps

On this page

Changing Languages

Available Methods

Using the `useSetLocale` hook

Using the `<LocaleSelector>` component

Using the `useLocaleSelector` hook

URL-based Language Switching

Important Notes

Client Components Only

GTProvider Requirement

Next Steps

On this page