Changing Languages

Overview

In this guide, we'll show you how to change the language of your Next.js app.

If you have not yet setup your app with gt-next, please refer to the quickstart guide before continuing.

There are three ways to change the language of your app using gt-next.

Using the useSetLocale() hook
Using the <LocaleSelector> component
Using the useLocaleSelector() hook
Using middleware i18n routing

We'll cover the first three methods in this guide. See the middleware routing guide for more information on how to change the language of your app using middleware.

Using the `useSetLocale` hook

The useSetLocale hook is a client-side hook that allows you to change the language of your app. It must be used within a GTProvider component.

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 callback function returned by the useSetLocale hook.

Using the `<LocaleSelector>` component

The <LocaleSelector> component is a client-side component that allows you to change the language of your app. It must be used within a GTProvider component.

This is a bare-bones UI dropdown that displays all the locales you have enabled in your project, and allows users to select a different locale.

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

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

Using the `useLocaleSelector` hook

Alternatively, if you would like to create your own locale selector component, you can use the useLocaleSelector hook.

This hook returns the current locale, the list of locales your project supports, and the useSetLocale hook.

Here is an example of how to use the useLocaleSelector hook to create a custom locale selector component.

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

function capitalizeLanguageName(language: string): string {
  if (!language) return '';
  return (
    language.charAt(0).toUpperCase() +
    (language.length > 1 ? language.slice(1) : '')
  );
}

export default function LocaleDropdown({ className }: { className?: string }) {
  // Retrieve the locale, locales, and setLocale function
  const { locale, locales, setLocale } = useLocaleSelector();

  // Helper function to get the display name of a locale
  const getDisplayName = (locale: string) => {
    return capitalizeLanguageName(
      getLocaleProperties(locale).nativeNameWithRegionCode
    );
  };

  // If no locales are returned, just render nothing or handle gracefully
  if (!locales || locales.length === 0 || !setLocale) {
    return null;
  }

  return (
    <Select onValueChange={setLocale} defaultValue={locale}>
      <SelectTrigger>
        <SelectValue placeholder='Select language' />
      </SelectTrigger>
      <SelectContent className='z-[200!important]' position='popper'>
        <SelectGroup>
          {!locale && <SelectItem value='' />}

          {locales.map((locale) => (
            <SelectItem key={locale} value={locale} suppressHydrationWarning>
              {getDisplayName(locale)}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  );
}

See the API reference for more information.

Next steps

Learn more about the useSetLocale hook.
Learn more about the <LocaleSelector> component.
Learn more about the useLocaleSelector hook.
Learn more about middleware i18n routing.

Changing Languages

Overview

Using the useSetLocale hook

Using the <LocaleSelector> component

Using the useLocaleSelector hook

Next steps

On this page

Using the `useSetLocale` hook

Using the `<LocaleSelector>` component

Using the `useLocaleSelector` hook