Internationalization of Server & Client Components

React Server Components (opens in a new tab) allow you to implement components that remain server-side only if they don’t require React’s interactive features, such as useState and useEffect.

This applies to handling internationalization too.

import {useTranslations} from 'next-intl';
 
// Since this component doesn't use any interactive features
// from React, it can be run as a Server Component.
 
export default function Index() {
  const t = useTranslations('Index');
  return <h1>{t('title')}</h1>;
}

Moving internationalization to the server side unlocks new levels of performance, leaving the client side for interactive features.

Benefits of server-side internationalization:

1. Your messages never leave the server and don't need to be passed to the client side
2. Library code for internationalization doesn't need to be loaded on the client side
3. No need to split your messages, e.g. based on routes or components
4. No runtime cost on the client side

Using internationalization in Server Components

Server Components can be declared in two ways:

1. Async components
2. Non-async, regular components

In a typical app, you'll likely find both types of components. next-intl provides corresponding APIs that work for the given component type.

Async components

These are primarly concerned with fetching data and can not use hooks (opens in a new tab). Due to this, next-intl provides a set of awaitable versions of the functions that you usually call as hooks from within components.

import {getTranslations} from 'next-intl/server';
 
export default async function ProfilePage() {
  const user = await fetchUser();
  const t = await getTranslations('ProfilePage');
 
  return (
    <PageLayout title={t('title', {username: user.name})}>
      <UserDetails user={user} />
    </PageLayout>
  );
}

These functions are available:

import {
  getTranslations,
  getFormatter,
  getNow,
  getTimeZone,
  getMessages,
  getLocale
} from 'next-intl/server';
 
const t = await getTranslations('ProfilePage');
const format = await getFormatter();
const now = await getNow();
const timeZone = await getTimeZone();
const messages = await getMessages();
const locale = await getLocale();

Non-async components

Components that aren't declared with the async keyword and don't use interactive features like useState, are referred to as shared components (opens in a new tab). These can render either as a Server or Client Component, depending on where they are imported from.

In Next.js, Server Components are the default, and therefore shared components will typically execute as Server Components.

import {useTranslations} from 'next-intl';
 
export default function UserDetails({user}) {
  const t = useTranslations('UserProfile');
 
  return (
    <section>
      <h2>{t('title')}</h2>
      <p>{t('followers', {count: user.numFollowers})}</p>
    </section>
  );
}

If you import useTranslations, useFormatter, useLocale, useNow and useTimeZone from a shared component, next-intl will automatically provide an implementation that works best for the environment this component executes in (server or client).

Using internationalization in Client Components

Depending on your situation, you may need to handle internationalization in Client Components as well. While providing all messages to the client side is typically the easiest way to get started and a reasonable approach for many apps, you can be more selective about which messages are passed to the client side if you're interested in optimizing the performance of your app.

There are several options for using translations from next-intl in Client Components, listed here in order of enabling the best performance:

Option 1: Passing translations to Client Components

The preferred approach is to pass the processed labels as props or children from a Server Component.

import {useTranslations} from 'next-intl';
import Expandable from './Expandable'; // A Client Component
import FAQContent from './FAQContent';
 
export default function FAQEntry() {
  // Call `useTranslations` in a Server Component ...
  const t = useTranslations('FAQEntry');
 
  // ... and pass translated content to a Client Component
  return (
    <Expandable title={t('title')}>
      <FAQContent content={t('description')} />
    </Expandable>
  );
}

'use client';
 
import {useState} from 'react';
 
function Expandable({title, children}) {
  const [expanded, setExpanded] = useState(false);
 
  function onToggle() {
    setExpanded(!expanded);
  }
 
  return (
    <div>
      <button onClick={onToggle}>{title}</button>
      {expanded && <div>{children}</div>}
    </div>
  );
}

By doing this, we can use interactive features from React like useState on translated content, even though the translation only runs on the server side.

Learn more in the Next.js docs: Passing Server Components to Client Components as Props (opens in a new tab)

import {useLocale, useTranslations} from 'next-intl';
import {locales} from 'config';
 
// A Client Component that registers an event listener for
// the `change` event of the select, uses `useRouter`
// to change the locale and uses `useTransition` to display
// a loading state during the transition.
import LocaleSwitcherSelect from './LocaleSwitcherSelect';
 
export default function LocaleSwitcher() {
  const t = useTranslations('LocaleSwitcher');
  const locale = useLocale();
 
  return (
    <LocaleSwitcherSelect defaultValue={locale} label={t('label')}>
      {locales.map((cur) => (
        <option key={cur} value={cur}>
          {t('locale', {locale: cur})}
        </option>
      ))}
    </LocaleSwitcherSelect>
  );
}

import {useTranslations} from 'next-intl';
 
// A Client Component, so that `useFormState` can be used
// to potentially display errors received after submission.
import RegisterForm from './RegisterForm';
 
// A Client Component, so that `useFormStatus` can be used
// to disable the input field during submission.
import FormField from './FormField';
 
// A Client Component, so that `useFormStatus` can be used
// to disable the submit button during submission.
import FormSubmitButton from './FormSubmitButton';
 
export default function RegisterPage() {
  const t = useTranslations('RegisterPage');
 
  function registerUser() {
    'use server';
    // ...
  }
 
  return (
    <RegisterForm action={registerUser}>
      <FormField label={t('firstName')} name="firstName" />
      <FormField label={t('lastName')} name="lastName" />
      <FormField label={t('email')} name="email" />
      <FormField label={t('password')} name="password" />
      <FormSubmitButton label={t('submit')} />
    </RegisterForm>
  );
}

Option 2: Moving state to the server side

You might run into cases where you have dynamic state, such as pagination, that should be reflected in translated messages.

function Pagination({curPage, totalPages}) {
  const t = useTranslations('Pagination');
  return <p>{t('info', {curPage, totalPages})}</p>;
}

You can still manage your translations on the server side by using:

1. Page or search params
2. Cookies
3. Database state

In particular, page and search params are often a great option because they offer additional benefits such as preserving the state of the app when the URL is shared, as well as integration with the browser history.

Option 3: Providing individual messages

To reduce bundle size, next-intl doesn't automatically provide messages or formats to Client Components.

If you need to incorporate dynamic state into components that can not be moved to the server side, you can wrap these components with NextIntlClientProvider and provide the relevant messages.

import pick from 'lodash/pick';
import {NextIntlClientProvider, useMessages} from 'next-intl';
import ClientCounter from './ClientCounter';
 
export default function Counter() {
  // Receive messages provided in `i18n.ts` …
  const messages = useMessages();
 
  return (
    <NextIntlClientProvider
      messages={
        // … and provide the relevant messages
        pick(messages, 'ClientCounter')
      }
    >
      <ClientCounter />
    </NextIntlClientProvider>
  );
}

Option 4: Providing all messages

If you're building a highly dynamic app where most components use React's interactive features, you may prefer to make all messages available to Client Components.

import {NextIntlClientProvider} from 'next-intl';
import {getMessages} from 'next-intl/server';
 
export default async function RootLayout(/* ... */) {
  // Receive messages provided in `i18n.ts`
  const messages = await getMessages();
 
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

Troubleshooting

"Failed to call useTranslations because the context from NextIntlClientProvider was not found."

You might encounter this error or a similar one referencing useFormatter while working on your app.

This can happen because:

1. You're intentionally calling the hook from a Client Component, but NextIntlClientProvider is not present as an ancestor in the component tree. If this is the case, you can wrap your component in NextIntlClientProvider to resolve this error.
2. The component that calls the hook accidentally ended up in a client-side module graph, but you expected it to render as a Server Component. If this is the case, try to pass this component via children to the Client Component instead.

"Functions cannot be passed directly to Client Components because they're not serializable."

You might encounter this error when you try to pass a non-serializable prop to NextIntlClientProvider.

The component accepts the following props that are not serializable:

1. onError
2. getMessageFallback
3. Rich text elements for defaultTranslationValues

To configure these, you can wrap NextIntlClientProvider with another component that is marked with 'use client' and defines the relevant props:

'use client';
 
import {NextIntlClientProvider} from 'next-intl';
 
export default function MyCustomNextIntlClientProvider({
  locale,
  timeZone,
  now,
  ...rest
}) {
  return (
    <NextIntlClientProvider
      // Define non-serializable props here
      defaultTranslationValues={{
        i: (text) => <i>{text}</i>
      }}
      // Make sure to forward these props to avoid markup mismatches
      locale={locale}
      timeZone={timeZone}
      now={now}
      {...props}
    />
  );
}

By doing this, your custom provider will already be part of the client-side bundle and can therefore define and pass functions as props.

Important: Be sure to pass explicit locale, formats, timeZone and now props to NextIntlClientProvider in this case, since the props aren't automatically inherited from a Server Component when you import NextIntlClientProvider from a Client Component.