Next.js 13: Internationalization (i18n) in Client Components

Next.js 13 introduces support for React Server Components (opens in a new tab) with the App Router. While support for Server Components in next-intl is on the horizon, you can continue to use next-intl in the app directory by deferring the usage of internationalization to Client Components.

Getting started

If you haven't done so already, create a Next.js 13 app that uses the app directory (opens in a new tab). The goal is to prefix all routes with the locale, so that we can retrieve it as a dynamic segment (opens in a new tab) and use it to configure next-intl.

Start by creating the following file structure:

├── messages (1)
│   ├── en.json
│   └── ...
├── middleware.ts (2)
└── app
    └── [locale]
        ├── layout.tsx (3)
        └── page.tsx (4)

Now, set up these files as follows:

`messages/en.json`

Messages can be provided locally or loaded from a remote data source (e.g. a translation management system). Use whatever suits your workflow best.

The simplest option is to create JSON files locally based on locales, e.g. en.json.

messages/en.json

{
  "Index": {
    "title": "Hello world!"
  }
}

`middleware.ts`

The middleware matches a locale for the request and handles redirects and rewrites accordingly.

middleware.ts

import createMiddleware from 'next-intl/middleware';
 
export default createMiddleware({
  // A list of all locales that are supported
  locales: ['en', 'de'],
 
  // If this locale is matched, pathnames work without a prefix (e.g. `/about`)
  defaultLocale: 'en'
});
 
export const config = {
  // Skip all paths that should not be internationalized
  matcher: ['/((?!api|_next|.*\\..*).*)']
};

`app/[locale]/layout.tsx`

Provide the document layout and set up NextIntlClientProvider.

app/[locale]/layout.tsx

import {NextIntlClientProvider} from 'next-intl';
import {notFound} from 'next/navigation';
 
export function generateStaticParams() {
  return [{locale: 'en'}, {locale: 'de'}];
}
 
export default async function LocaleLayout({children, params: {locale}}) {
  let messages;
  try {
    messages = (await import(`../../messages/${locale}.json`)).default;
  } catch (error) {
    notFound();
  }
 
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider locale={locale} messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

`app/[locale]/page.tsx`

Turn your page component into a Client Component to be able to use translations.

app/[locale]/page.tsx

'use client';
 
import {useTranslations} from 'next-intl';
 
export default function Index() {
  const t = useTranslations('Index');
  return <h1>{t('title')}</h1>;
}

That's all you need to do to start using translations in the app directory!

If you've encountered an issue, you can explore the code for a working example (opens in a new tab) (demo (opens in a new tab)).

💡

Note that you have to mark all components that use features from next-intl with 'use client'; at the top of the module if you use this approach. Support for next-intl APIs in Server Components is available in a beta version.

Usage with the Metadata API

To provide metadata for a route, you can use the core library from next-intl.

app/[locale]/layout.tsx

import {createTranslator} from 'next-intl';
 
export async function generateMetadata({params: {locale}}) {
  const messages = (await import(`../../../messages/${locale}.json`)).default;
 
  // You can use the core (non-React) APIs when you
  // have to use next-intl outside of components.
  const t = createTranslator({locale, messages});
 
  return {
    title: t('LocaleLayout.title')
  };
}

💡

Potentially, this will be simplified in the future (see the Server Components beta docs).

Getting started Server Components (beta)