Internationalization in Next.js with the App Router and next-intl. A step-by-step guide.

Creating web applications that cater to a global audience requires more than just translating text; it demands a comprehensive approach to internationalization (i18n). Next.js, with its cutting-edge App Router, coupled with next-intl, provides a robust foundation for building multilingual applications. This guide offers a step-by-step walkthrough on setting up internationalization in your Next.js project, ensuring your application is accessible and user-friendly for a worldwide audience.

Prerequisites

Before diving in, ensure you have Node.js installed on your system and are familiar with the basics of React and Next.js.

Step 1: Setting Up Your Next.js Project

Begin by creating a new Next.js project if you haven’t done so already:

npx create-next-app@latest my-next-global-app
cd my-next-global-app

This command scaffolds a new Next.js application in the directory my-next-global-app.

Step 2: Integrating next-intl

next-intl is a library that facilitates internationalization in Next.js projects, offering features like localized messages and date/time formatting.

Install next-intl by running:

npm install next-intl

Step 3: Structuring Your Project for Internationalization

For effective internationalization, organize your project files to include localization resources and configuration files. Here’s the recommended structure:

my-next-global-app
├── messages
│   ├── en.json
│   ├── fr.json
│   └── ...
├── next.config.mjs
└── src
    ├── i18n.ts
    ├── middleware.ts
    └── app
        └── [locale]
            ├── layout.tsx
            └── page.tsx

Localization Messages

Create JSON files within the messages directory for each locale you plan to support (e.g., en.json for English, fr.json for French). These files will contain the localized strings for your application.

Example en.json:

{
  "greeting": "Hello, world!"
}

Example fr.json:

{
  "greeting": "Bonjour, le monde!"
}

Step 4: Configuring next-intl and Next.js

'next.config.mjs'

Configure Next.js to use next-intl for internationalization support:

import createNextIntlPlugin from 'next-intl/plugin';

const withNextIntl = createNextIntlPlugin();

export default withNextIntl({
  // Your existing Next.js configuration here
});

'src/i18n.ts'

Set up a function to provide localization configurations based on the user’s locale. This involves loading the corresponding messages from the messages directory.

import { notFound } from 'next/navigation';
import { getRequestConfig } from 'next-intl/server';

const locales = ['en', 'fr']; // Define supported locales

export default getRequestConfig(async ({ locale }) => {
  if (!locales.includes(locale)) notFound(); // Validate locale
  
  return {
    messages: (await import(`../messages/${locale}.json`)).default
  };
});

'src/middleware.ts'

Implement middleware to handle locale detection and routing, specifying the supported locales and default locale:

import createMiddleware from 'next-intl/middleware';

export default createMiddleware({
  locales: ['en', 'fr'],
  defaultLocale: 'en',
});

export const config = {
  matcher: ['/', '/(en|fr)/:path*'],
};

Step 5: Utilizing Localized Content in Your Application

With the internationalization infrastructure in place, you can now use localized strings within your Next.js components.

Example Usage in a Page Component

In app/[locale]/page.tsx, utilize the useTranslations hook from next-intl to access and render localized content:

import { useTranslations } from 'next-intl';

export default function HomePage() {
  const t = useTranslations();
  
  return <h1>{t('greeting')}</h1>; // Dynamically renders "Hello, world!" or "Bonjour, le monde!"
}

Next Steps

Following this setup, your Next.js application is now equipped to serve content in multiple languages, adapting to the user’s locale. From here, you can expand your internationalization efforts by:

• Adding more locales and translations.
• Exploring date and number formatting with next-intl.
• Implementing advanced routing strategies to cater to different regional content and SEO requirements.

Conclusion

Embracing internationalization is a significant step towards making your Next.js application truly global. By following this guide, you’ve laid down a solid foundation for serving a multilingual user base, enhancing the accessibility and user experience of your application. As you expand your application’s global reach, remember to continuously adapt and refine your internationalization strategies to meet the diverse needs of your global audience.

In Plain English 🚀

Thank you for being a part of the In Plain English community! Before you go:

• Be sure to clap and follow the writer ️👏️️
• Follow us: X | LinkedIn | YouTube | Discord | Newsletter
• Visit our other platforms: Stackademic | CoFeed | Venture | Cubed
• More content at PlainEnglish.io