Next.js plugin (createNextIntlPlugin)

When setting up next-intl for the App Router, you’ll add next-intl/plugin to your Next.js config.

At the minimum, it will look like this:

import {NextConfig} from 'next';
import createNextIntlPlugin from 'next-intl/plugin';
 
const nextConfig: NextConfig = {};
 
const withNextIntl = createNextIntlPlugin();
export default withNextIntl(nextConfig);

For customization, you can provide options to the plugin.

requestConfig

By default, next-intl will look for a file called i18n/request.ts which returns request-specific configuration. This file is searched for both in the src folder as well as in the project root with the extensions .ts, .tsx, .js and .jsx.

If you prefer to move this file somewhere else, you can provide a path to the plugin:

const withNextIntl = createNextIntlPlugin(
  // Specify a custom path here
  './somewhere/else/request.ts'
);

Or if you’re combining this with other options, you can use the requestConfig option:

const withNextIntl = createNextIntlPlugin({
  requestConfig: './somewhere/else/request.ts'
});

experimental

For early adopters, the Next.js plugin provides various experimental options that let you try out new features before they’re released as stable.

createMessagesDeclaration

To enable type-safe message arguments, you can point the createMessagesDeclaration option to a sample messages file in order to create a strict declaration file for it.

const withNextIntl = createNextIntlPlugin({
  experimental: {
    // Provide the path to the messages that you're using in `AppConfig`
    createMessagesDeclaration: './messages/en.json'
  }
  // ...
});

See TypeScript augmentation to learn more about this.

Note: This is not necessary when using useExtracted.

extract

This enables the usage of useExtracted to automatically extract messages from source files.

const withNextIntl = createNextIntlPlugin({
  experimental: {
    extract: {
      // Defines which locale to extract to
      sourceLocale: 'en'
    }
    // ...
  }
});

Note: The extract option should be used together with messages and srcPath.

messages

This defines where and how messages for locales should be stored.

const withNextIntl = createNextIntlPlugin({
  experimental: {
    messages: {
      // Relative path to the directory
      path: './messages',
 
      // Automatically detects locales based on `path`
      locales: 'infer',
 
      // Either 'json' or 'po'
      format: 'json'
    }
    // ...
  }
});

If you want to specify the locales explicitly, you can provide an array for locales:

locales: ['en', 'de'];

Configuring experimental.messages will also set up a Turbo- or Webpack loader that will ensure loaded messages can be imported as plain JavaScript objects (see formatters).

Note: The messages option should be used together with extract and srcPath.

srcPath

This defines the source path where messages should be extracted from.

const withNextIntl = createNextIntlPlugin({
  experimental: {
    srcPath: './src'
    // ...
  }
});

If your project is split into multiple folders, you can provide an array of paths:

// Not using a `src` folder
srcPath: ['./app', './components'],

// Multiple packages in a monorepo
srcPath: ['./src', '../ui'],

// External dependency on a package
srcPath: ['./src', './node_modules/@acme/components'],

If you want to provide messages along with your package, you can also extract them manually.

Note: The srcPath option should be used together with extract and messages.