Implementing i18n in Next.js 15 App Router: A Complete Guide

Introduction

Building a multilingual app in Next.js 15 App Router can be challenging, but with the right tools, it becomes seamless. Internationalization (i18n) ensures that your app can support multiple languages, improving user experience and SEO for global audiences.

In this guide, we'll walk through implementing i18n in Next.js 15 using next-intl. You'll learn how to:

Set up translations
Configure language-based routing
Handle middleware for automatic locale detection
Overcome common i18n challenges

By the end, your Next.js app will be fully multilingual and optimized for international users!

Why next-intl?

With the introduction of App Router in Next.js 15, managing internationalization (i18n) has changed significantly. Unlike previous versions, where libraries like next-i18next relied on getStaticProps and getServerSideProps, the new Server Components architecture requires a different approach.

Here’s why next-intl is the best choice for i18n in Next.js 15:

Full Compatibility with App Router – Works seamlessly with Server & Client Components.
Automatic Locale Detection – Uses middleware to handle redirects and rewrites.
Improved SEO – Supports localized URLs for better search engine visibility.
Flexible Translation Management – Load translations dynamically for optimized performance.
Lightweight & Easy to Use – Minimal setup without unnecessary complexity.

By using next-intl, we can build a clean, scalable, and efficient multilingual app in Next.js 15 App Router while leveraging the latest Next.js features.

Setup

To start using i18n in Next.js 15 App Router, we need to install the necessary package and structure our project correctly. If you haven’t set up your Next.js app yet, do so first, then install next-intl:

npm install next-intl

Now, let’s organize the project to support internationalization in Next.js 15 App Router:

├── messages
│   ├── en.json (1)
│   └── ...
├── next.config.mjs (2)
└── src
    ├── i18n
    │   ├── routing.ts (3)
    │   └── request.ts (5)
    ├── middleware.ts (4)
    └── app
        └── [locale]
            ├── layout.tsx (6)
            └── page.tsx (7)

If you're migrating an existing Next.js app to next-intl, move your pages into the [locale] folder to integrate them into i18n in Next.js 15 App Router.

1. Adding Translation Files

Every language needs its own translations. The simplest way is by storing text inside JSON files in a messages directory.

messages/en.json

{
  "HomePage": {
    "title": "Hello world!",
    "about": "Go to the about page"
  }
}

These files hold the localized content for your app, forming the core of i18n in Next.js 15 App Router.

2. Configuring Next.js for i18n

Next, we modify next.config.mjs to integrate next-intl. This ensures each request retrieves the correct language settings.

next.config.ts

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

This configuration is crucial for handling translations dynamically in i18n in Next.js 15 App Router.

3. Setting Up Routing

Routing plays a key role in i18n in Next.js 15 App Router. This setup enables locale-based URLs like /en/about without additional manual handling.

src/i18n/routing.ts

import {defineRouting} from 'next-intl/routing';
import {createNavigation} from 'next-intl/navigation';
export const routing = defineRouting({
  // List of supported languages
  locales: ['en', 'de'],
  // Default language
  defaultLocale: 'en'
});
// Custom navigation helpers to work with i18n paths
export const {Link, redirect, usePathname, useRouter, getPathname} =
  createNavigation(routing);

With this, your app will automatically handle locale-based navigation, a crucial feature of i18n in Next.js 15 App Router.

4. Adding Middleware for Locale Detection

Middleware ensures that users are redirected to their preferred language automatically.

src/middleware.ts

import createMiddleware from 'next-intl/middleware';
import {routing} from './i18n/routing';
export default createMiddleware(routing);
export const config = {
  // Apply middleware only to localized routes
  matcher: ['/', '/(de|en)/:path*']
};

This step is essential for smooth user experience and SEO in i18n in Next.js 15 App Router.

5. Handling Locale Configuration in Server Components

To make translations available in Server Components, we create a centralized configuration file.

src/i18n/request.ts

import {getRequestConfig} from 'next-intl/server';
import {routing} from './routing';
export default getRequestConfig(async ({requestLocale}) => {
  // Determine the correct locale from the request
  let locale = await requestLocale;
  // Fallback to default locale if needed
  if (!locale || !routing.locales.includes(locale as any)) {
    locale = routing.defaultLocale;
  }
  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default
  };
});

This step allows i18n in Next.js 15 App Router to correctly load translations for each request.

6. Configuring the Layout for Localization

The layout component ensures the correct document language and passes translations to Client Components.

src/app/[locale]/layout.tsx

import {NextIntlClientProvider} from 'next-intl';
import {getMessages} from 'next-intl/server';
import {notFound} from 'next/navigation';
import {routing} from '@/i18n/routing';
export default async function LocaleLayout({
  children,
  params: {locale}
}: {
  children: React.ReactNode;
  params: {locale: string};
}) {
  // Ensure the locale is valid
  if (!routing.locales.includes(locale as any)) {
    notFound();
  }
  // Load translations for the client
  const messages = await getMessages();
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

This step guarantees a properly structured multilingual experience, a key part of i18n in Next.js 15 App Router.

7. Using Translations in Pages

Now, let’s put everything together and use translations inside a page component.

src/app/[locale]/page.tsx

import {useTranslations} from 'next-intl';
import {Link} from '@/i18n/routing';
export default function HomePage() {
  const t = useTranslations('HomePage');
  return (
    <div>
      <h1>{t('title')}</h1>
      <Link href="/about">{t('about')}</Link>
    </div>
  );
}

Common Challenges & Fixes

Hiding 'en' in URLs: Avoid Unnecessary Language Prefixes

By default, Next.js includes the language code in the URL, such as /en/about for English content. If English is your default language, you may not want to show the language prefix (/en) for URLs like /about, as it can make your URLs unnecessarily longer and less clean.

To hide the language prefix for the default locale, you need to configure the localePrefix option in your routing setup. Here’s how you can do it:

Modify Your Routing Configuration

In your src/i18n/routing.ts file, add the localePrefix: "as-needed" configuration:

import { defineRouting } from "next-intl/routing";
import { createNavigation } from "next-intl/navigation";
export const routing = defineRouting({
  // A list of all locales that are supported
  locales: ["en", "ar"], // Add all the languages your app supports
  localePrefix: "as-needed", // Hide the 'en' prefix for the default language
  // Used when no locale matches
  defaultLocale: "en", // Set English as the default language
});
// Lightweight wrappers around Next.js' navigation APIs
// that will consider the routing configuration
export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

Explanation

localePrefix: "as-needed": This ensures that the default locale ("en") does not show in the URL unless the user explicitly changes the language. So, users will visit /about without the /en prefix, but if they switch to Arabic (/ar/about), it will add the /ar prefix.
Why it’s important: This setup keeps your URLs clean and user-friendly. It ensures that the default language is handled seamlessly without cluttering your URL structure, making the website easier to navigate and more SEO-friendly.

With this configuration, you can offer multiple languages while avoiding redundancy in URLs for your default locale.

Handling Invalid Locales: Redirecting to 404 Properly

In Next.js, the notFound function is used to render a 404 page when a route does not exist. You can leverage this to create a localized 404 page that will display based on the current locale.

To handle this for invalid locales or non-existent pages, follow these steps:

Creating a Localized 404 Page

First, create a localized 404 page inside the [locale] folder. For example, you can create not-found.tsx under app/[locale]/ to display a translated message when a route does not exist:

// app/[locale]/not-found.tsx
import { useTranslations } from 'next-intl';
export default function NotFoundPage() {
  const t = useTranslations('NotFoundPage');
  return <h1>{t('title')}</h1>;
}

How this works: The useTranslations hook pulls the appropriate translation for the NotFoundPage based on the current locale. For example, if the user is in English (/en), it will show the English 404 message; if in Arabic (/ar), it will show the Arabic version.

Catching Unknown Routes

By default, Next.js will render the closest not-found.tsx when a route segment calls the notFound function. However, if you want to catch all unknown routes within the localized route, you need to set up a catch-all route that explicitly calls the notFound function.

Create a catch-all route in app/[locale]/[...rest]/page.tsx to handle any invalid routes:

// app/[locale]/[...rest]/page.tsx
import { notFound } from 'next/navigation';
export default function CatchAllPage() {
  notFound();
}

How this works: Any route within the [locale] segment that doesn’t match a valid path will trigger the notFound function, rendering the localized 404 page (not-found.tsx).

Now, when users try to access invalid routes like /en/unknown or /ar/unknown, they will be redirected to a localized 404 page, improving the user experience and maintaining consistency across different languages.

Preserving Locale in Links: Avoiding Unexpected Navigation Issues

When working with multiple languages in your Next.js application, it’s essential to ensure that your navigation links preserve the current locale. By default, Next.js handles the Link component, but when using next-intl for internationalization, we need to use the special Link component exported from our custom routing.ts to handle locale-specific navigation.

Here's how you can set it up and keep the correct locale in your links:

Using the Link Tag from next-intl

First, make sure you’re importing the custom Link component from src/i18n/routing.ts (which was defined earlier).

Here’s how you can use it to create locale-preserving navigation:

// app/[locale]/page.tsx
import { Link } from '@/i18n/routing';
import { useTranslations } from 'next-intl';
export default function HomePage() {
  const t = useTranslations('HomePage');
  return (
    <div>
      <h1>{t('title')}</h1>
      {/* Locale-preserving Link */}
      <Link href="/about">{t('about')}</Link>
    </div>
  );
}

Conclusion

Implementing Next.js 15 App Router with next-intl for internationalization (i18n) can significantly improve the user experience on your multilingual website. By following the setup and tackling common challenges, such as hiding the default language prefix, handling invalid locales, and preserving the locale in navigation links, you can create a seamless, SEO-friendly, and scalable solution for any internationalized Next.js app.

The next-intl package makes it easy to integrate internationalization into your Next.js 15 app, ensuring that the routing, locale handling, and message management are all optimized for different languages. With a simple yet powerful configuration, you can deliver localized content to your users without compromising performance or SEO.

By following the steps outlined in this blog, you should now be equipped to implement next-intl in your Next.js project. Keep in mind the common pitfalls and fixes we've discussed to ensure smooth internationalization for both users and developers alike. Happy coding!

BAHADOR

CODES