# gt-next: General Translation Next.js SDK: Changing Languages
URL: https://generaltranslation.com/en-US/docs/next/guides/languages.mdx
---
title: Changing Languages
description: How to configure and switch between languages in your Next.js app
---

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`](/docs/next/api/helpers/use-set-locale) hook for custom controls
- **Pre-built UI**: [`<LocaleSelector>`](/docs/next/api/components/locale-selector) component with dropdown
- **Custom UI**: [`useLocaleSelector`](/docs/next/api/helpers/use-locale-selector) hook for building custom selectors
- **URL-based**: [Middleware routing](/docs/next/guides/middleware) for locale in URL paths

## Using the `useSetLocale` hook

The [`useSetLocale`](/docs/next/api/helpers/use-set-locale) hook is a client-side hook that allows you to change the language of your app:

```tsx
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>`](/docs/next/api/components/locale-selector) component provides a ready-to-use dropdown that automatically shows all configured locales:

```tsx
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`](/docs/next/api/helpers/use-locale-selector):

```tsx
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](/docs/next/guides/middleware):

```
/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'`:

```tsx
'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>`](/docs/next/api/components/gtprovider):

```tsx
// ✅ Correct
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ Wrong - outside provider
<LanguageSwitcher />
```

## Next steps

- [Middleware Guide](/docs/next/guides/middleware) - URL-based language routing
- [Dynamic Content Guide](/docs/next/guides/dynamic-content) - Runtime content translation  
- API References:
  - [`useSetLocale` Hook](/docs/next/api/helpers/use-set-locale)
  - [`<LocaleSelector>` Component](/docs/next/api/components/locale-selector)