# Step-by-Step Guide to Implementing i18n in Next.js with next-intl > Learn how to add internationalization to your Next.js App Router project using next-intl. Complete walkthrough from installation to production deployment. - **Author**: Mohit Sapat - **Published**: 2026-08-10 - **URL**: https://www.babelize.co/blogs/implement-i18n-nextjs-next-intl ---

Adding internationalization to a Next.js application used to involve complex configuration, third-party backends, and wrestling with server-side rendering quirks. With next-intl and the App Router, that story has changed completely. This guide walks you through every step of implementing i18n in a Next.js 14+ project -- from installation to a production-ready multilingual app.

Why next-intl?

next-intl is purpose-built for Next.js. Unlike framework-agnostic alternatives that require additional wrappers and workarounds, next-intl integrates with the App Router, React Server Components, Middleware, and Server Actions natively. This means faster page loads, smaller client bundles, and a developer experience that feels like a natural extension of Next.js itself. Still deciding? Our next-intl vs react-i18next comparison covers when the alternative is the better fit.

By the end of this guide, you'll have a Next.js app that serves content in multiple languages, detects user locale preferences, and handles fallback gracefully -- all in under 100 lines of configuration.

Step 1: Install next-intl

Start by installing the package in your Next.js project:

npm install next-intl

That's it -- no additional plugins, no backends, no complex dependency trees. The library ships with everything you need for both server and client-side translations.

Step 2: Create Translation Files

Translation files are plain JSON files organized by locale (see JSON translation files explained for naming and structure conventions). Create a messages/ directory at your project root:

messages/
├── en.json
├── fr.json
├── es.json

Each file contains key-value pairs for that locale. Here's a minimal en.json:

{
  "HomePage": {
    "title": "Welcome to Our Platform",
    "description": "Build multilingual apps with confidence.",
    "cta": "Get Started"
  },
  "Navigation": {
    "home": "Home",
    "about": "About",
    "contact": "Contact Us"
  }
}

And the corresponding fr.json:

{
  "HomePage": {
    "title": "Bienvenue sur Notre Plateforme",
    "description": "Créez des applications multilingues en toute confiance.",
    "cta": "Commencer"
  },
  "Navigation": {
    "home": "Accueil",
    "about": "À propos",
    "contact": "Contactez-Nous"
  }
}

Tip: Use a nested structure to group translations by page or component. This keeps files organized as your application grows, and next-intl's type generation preserves the nesting for autocomplete.

Step 3: Configure Middleware

Create src/middleware.ts to handle locale detection and URL rewriting:

import createMiddleware from "next-intl/middleware";
import { routing } from "./i18n/routing";

export default createMiddleware(routing);

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

Next, create src/i18n/routing.ts to define your supported locales:

import { defineRouting } from "next-intl/routing";

export const routing = defineRouting({
  locales: ["en", "fr", "es"],
  defaultLocale: "en",
  localePrefix: "as-needed",
});

The middleware does three things automatically:

Detects the user's preferred locale from the URL or Accept-Language header
Redirects un-prefixed URLs to the correct locale (e.g., /about becomes /en/about)
Rewrites the URL internally so your server components receive the locale via params.locale

Step 4: Create i18n Request Config

Create src/i18n/request.ts to load the correct translation messages for each request:

import { getRequestConfig } from "next-intl/server";
import { routing } from "./routing";

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale;

  if (!locale || !routing.locales.includes(locale as any)) {
    locale = routing.defaultLocale;
  }

  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default,
  };
});

This function runs for every request, loads the appropriate JSON file, and makes the messages available throughout your component tree. The fallback to the default locale ensures your app never breaks if a user requests an unsupported language.

Step 5: Wire Up the Plugin

Add next-intl to your next.config.ts:

import type { NextConfig } from "next";
import createNextIntlPlugin from "next-intl/plugin";

const withNextIntl = createNextIntlPlugin("./src/i18n/request.ts");

const nextConfig: NextConfig = {};

export default withNextIntl(nextConfig);

This plugin ensures the request configuration is picked up during the build and that the i18n routing works correctly across all environments.

Step 6: Wrap Your Layout

Update your root layout at 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,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;

  if (!routing.locales.includes(locale as any)) {
    notFound();
  }

  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

The NextIntlClientProvider makes translations available to all components within the tree. The notFound() call handles invalid locale URLs gracefully.

Step 7: Using Translations in Components

Server Components

Use getTranslations() for server components. These run entirely on the server with zero client-side JavaScript:

import { getTranslations } from "next-intl/server";

export default async function HomePage() {
  const t = await getTranslations("HomePage");

  return (
    <main>
      <h1>{t("title")}</h1>
      <p>{t("description")}</p>
      <button>{t("cta")}</button>
    </main>
  );
}

Client Components

For interactive components, use the useTranslations() hook:

"use client";

import { useTranslations } from "next-intl";

export function Navigation() {
  const t = useTranslations("Navigation");

  return (
    <nav>
      <a href="/">{t("home")}</a>
      <a href="/about">{t("about")}</a>
      <a href="/contact">{t("contact")}</a>
    </nav>
  );
}

The key distinction: getTranslations() is an async function for Server Components, while useTranslations() is a synchronous hook for Client Components. next-intl handles the boundary seamlessly.

Step 8: Dynamic Values and Pluralization

next-intl supports ICU message syntax for dynamic content:

{
  "Cart": {
    "itemCount": "You have {count, plural, =0 {no items} =1 {one item} other {# items}} in your cart.",
    "welcome": "Hello, {name}!"
  }
}

Usage in components:

t("Cart.itemCount", { count: 3 });  // "You have 3 items in your cart."
t("Cart.welcome", { name: "Marie" });  // "Hello, Marie!"

The ICU syntax handles pluralization, gender, and complex formatting rules across all supported locales automatically. Our ICU MessageFormat guide covers plural categories, select, and nesting in depth.

Step 9: Language Switcher

Build a locale switcher using next-intl's navigation utilities:

"use client";

import { usePathname, useRouter } from "@/i18n/navigation";
import { useLocale } from "next-intl";

const languages = [
  { code: "en", label: "English" },
  { code: "fr", label: "Français" },
  { code: "es", label: "Español" },
] as const;

export function LanguageSwitcher() {
  const pathname = usePathname();
  const router = useRouter();
  const locale = useLocale();

  return (
    <select
      value={locale}
      onChange={(e) => router.push(pathname, { locale: e.target.value })}
    >
      {languages.map(({ code, label }) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

The usePathname and useRouter from @/i18n/navigation automatically handle locale prefixes in URLs, so navigation between locales is seamless.

Step 10: Typed Translations

next-intl gets its types straight from your source-language messages file, so there is no separate generation step. Declare them once in a global.d.ts file at the project root:

import messages from "./messages/en.json";

declare module "next-intl" {
  interface AppConfig {
    Messages: typeof messages;
  }
}

Make sure "resolveJsonModule": true is set in your tsconfig.json so the JSON import type-checks.

Now your IDE will autocomplete translation keys, catch typos at compile time, and show inline documentation for every message in your translation files.

Common Gotchas and Solutions

Client component hydration mismatch: Ensure NextIntlClientProvider wraps your entire app in the root layout, not in individual pages.
404 on locale pages: Double-check that your middleware matcher includes all locale prefixes and that routing.locales matches your folder structure.
Missing translations: Use the onError callback in your request config to log missing keys during development without crashing. If messages come from a translation API at request time, plan for outages with timeouts, cached fallbacks, and retries.
SEO considerations: Add hreflang tags and canonical URLs for each locale to avoid duplicate content issues. The hreflang and multilingual SEO guide shows how to generate them in Next.js.
Translation management: As your app grows to 10+ languages, manually editing JSON files becomes tedious. Use automated localization tools like Babelize to sync translations, manage glossaries, and keep all locale files in sync without manual copy-pasting.

Production Checklist

All translation keys exist in every locale JSON file
RTL layouts tested if supporting Arabic, Hebrew, or other RTL scripts
Dynamic content (dates, numbers, currencies) uses Intl formatting
hreflang tags are present on every page
Language switcher preserves current page, not just redirects to home
404 and error pages are also localized
Translation files are excluded from client bundles (next-intl handles this automatically)

Next Steps

At this point, you have a fully functional multilingual Next.js application. From here, consider:

Automating translations -- Babelize can translate your JSON files in bulk, keep them in sync as you iterate, and even create GitHub PRs with the updated locale files. See the Babelize Next.js docs to wire it into this setup.
Adding more locales -- next-intl scales effortlessly. Just add another JSON file and update your routing.ts.
Advanced patterns -- Explore next-intl's support for rich text translations, ICU message formatting, and per-component message splitting.

The hardest part of i18n isn't the library -- it's maintaining translations as your product evolves. next-intl eliminates the technical complexity. Tools like Babelize eliminate the operational complexity.

--- - [All articles](https://www.babelize.co/blogs)