Internationalization in Next.js error files

The Next.js file convention provides two files that can be used for error handling:

While not-found.js can either be a Server or Client Component, the latter two files require to be Client Components. Therefore depending on the file, you have to make sure that you're providing configuration like messages accordingly.

This page provides practical guides for these cases.

💡

Have a look at the App Router example to explore a working app with error handling.

`not-found.js`

Next.js renders the nearest not-found page when a route segment throws a notFound function (opens in a new tab). Since we rely on the [locale] segment to localize our app, the not-found page needs to be located within this segment.

app/[locale]/not-found.tsx

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

Note however that Next.js will only render this page, when the notFound function is thrown from within a route, not for all unknown routes in general.

Catching unknown routes

To catch unknown routes too, we can define a catch-all route that explicitly throws the notFound function.

app/[locale]/[...rest]/page.tsx

import {notFound} from 'next/navigation';
 
export default function CatchAllPage() {
  notFound();
}

After this change, all routes that are matched within the [locale] segment will render the defined not-found page when an unknown route is encountered.

Catching non-localized requests

When the user requests a route that is not matched by the next-intl middleware (depending on your matcher config), there's no locale associated with the request. You can add a root not-found page to handle these cases too (e.g. /unknown.txt).

app/not-found.tsx

'use client';
 
import Error from 'next/error';
 
// Render the default Next.js 404 page when a route
// is requested that doesn't match the middleware and
// therefore doesn't have a locale associated with it.
 
export default function NotFound() {
  return (
    <html lang="en">
      <body>
        <Error statusCode={404} />
      </body>
    </html>
  );
}

`error.js`

When an unexpected runtime error is encountered within your components, Next.js will gracefully handle the error by using the closest error file (opens in a new tab). When an error file is defined, Next.js will create an error boundary within your layout that wraps pages accordingly (opens in a new tab).

Since the error file must be defined as a Client Component, you have to use NextIntlClientProvider to provide messages in case the error file renders.

If you've set up next-intl to be used in Client Components (opens in a new tab), this is already the case and there's no additional setup needed. If you're using the Server Components beta, you have to provide the relevant messages in the wrapping layout.

app/[locale]/layout.tsx

import pick from 'lodash/pick';
 
// (only necessary when using the Server Components beta)
 
export default async function LocaleLayout({children}) {
  // ...
  const messages = useMessages();
 
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider
          locale={locale}
          messages={pick(messages, 'Error')}
        >
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

Once NextIntlClientProvider is in place, you can use next-intl APIs in the error file:

app/[locale]/error.tsx

'use client';
 
import {useTranslations} from 'next-intl';
 
export default function Error({error, reset}) {
  const t = useTranslations('Error');
 
  return (
    <div>
      <h1>{t('title')}</h1>
      <button onClick={reset}>{t('retry')}</button>
    </div>
  );
}

Metadata & Route Handlers Core library