Implementing i18n in Next.js 15 (App) using i18next

If you’ve made it to this article, you’re probably working on a multilingual site in Next.js 15+ using the new App Router. Good news: you’re in the right place. We're going to integrate internationalization (i18n) using i18next, react-i18next, next-i18n-router, and i18next-resources-to-backend.

Let’s build a setup that works on both server and client, doesn’t download translations twice, and won’t drive you (or your future self) crazy.

Initial Setup & Middleware Configuration

Step 1: Create a new Next.js App

Use the latest Next.js setup tool by running:

1npx create-next-app@latest my-next-i18n-app

This command will set up a fresh Next.js 15+ project with App Router.

Installing Dependencies

Before diving into the implementation, install the required packages:

1npm install i18next react-i18next i18next-resources-to-backend next-i18n-router

Or if you're using Yarn:

1yarn add i18next react-i18next i18next-resources-to-backend next-i18n-router

Step 2: Add a Dynamic Locale Route

Next, structure your application to support multiple languages dynamically. In the app directory, create a dynamic route folder named [locale]. Your directory structure will look like this:

This setup allows the app to handle different locales based on URL segments (/en, /ar, etc.).

Step 3: Create an i18n Configuration File

To manage locales, create a configuration file with your supported locales, default locale. For this guides purpose, we will assume you are using src directory.

Create src/lib/i18n/index.ts with this content.

import { AllowedLocales, Locale, I18NConfig } from "@/lib/types";

export const defaultLocale = "en";

export const allowedLocales: AllowedLocales = [defaultLocale, "ar"];

const i18nConfig: I18NConfig = {
  locales: allowedLocales,
  defaultLocale,
  prefixDefault: false, // avoids prefixing the default locale in URLs
};

export { i18nConfig };

Now it's time to define types. Create another file src/lib/types/index.ts

export type Locale = "en" | "ar";

export type AllowedLocales = Locale[];

export type I18NConfig = {
  locales: string[];
  defaultLocale: string;
  prefixDefault: boolean;
};

Step 4: Middleware Setup for Locale Route Handling

To automatically handle locale-specific routing, create a middleware file at the root level src/middleware.ts:

import { i18nRouter } from "next-i18n-router";
import { i18nConfig } from "./lib/i18n/index";

export function middleware(request: any) {
  return i18nRouter(request, i18nConfig);
}

// Apply middleware only to relevant routes (excluding API, static files, and internal Next.js paths)
export const config = {
  matcher: "/((?!api|static|.*\\..*|_next).*)",
};

Explanation:

This middleware intercepts incoming requests, checks for locale information, and automatically routes the request to the appropriate locale-based path.
The matcher ensures the middleware doesn't interfere with API endpoints or static assets.

Step 5: Set `lang` and `dir` inside Root Layout

Next we need to set lang and dir attribute on <html> tag inside root layout. For that we will write a utility function that gives us direction for active locale.
Inside src/lib/utils/index.ts

import type { Locale } from "./types";

export function getDirection(locale: Locale) {
  if (locale === "ar") {
    return "rtl";
  }
  return "ltr";
}

Let's use this utility function inside src/app/[locale]/layout.tsx which is also root layout of the Next.js app.

import { getDirection } from "@/lib/utils";
import { Locale } from "@/lib/types";

type RootLayoutProps = {
  children: React.ReactNode;
  params: Promise<{ locale: Locale }>;
};

export default async function RootLayout({
  children,
  params,
}: RootLayoutProps) {
  const { locale } = await params;
  return (
    <html lang={locale} dir={getDirection(locale)}>
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
          {children}
      </body>
    </html>
  );
}

Step 6: Add translations

Next we will add translations as JSON files inside src/lib/i18n/transalations that we will read in next steps. Create a structured directory to organize your translation JSON files:

/translations/en/home.json

{
  "welcome": "Welcome",
  "description": "This is an English description."
}

/translations/ar/home.json

{
  "welcome": "مرحبا",
  "description": "هذا وصف باللغة العربية."
}

Server side Internationalization (i18n)

In Next.js App Router, translations are loaded by default on the server side. Let's see how you can efficiently manage and consume translations.

Step 1: Create Server-side Translation Utility

Next, implement a utility that initializes and fetches translations server-side. We will export serverSideTranslation from src/lib/i18n/index.ts which helps us load translations anywhere on server (components, functions like generateMetadata).

src/lib/i18n/index.ts

import { createInstance, TFunction } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";
import resourcesToBackend from "i18next-resources-to-backend";
import { i18nConfig } from "@/lib/i18n/index";
import { Locale } from "../types/i18n";

async function initTranslations(
  locale: string,
  namespaces: string[],
  options?: { keyPrefix?: string; i18nInstance?: any; resources?: any }
) {
  const i18nInstance = options?.i18nInstance || createInstance();

  i18nInstance.use(initReactI18next);

  if (!options?.resources) {
    i18nInstance.use(
      resourcesToBackend(
        (language: string, namespace: string) =>
          import(`@/lib/i18n/translations/${language}/${namespace}.json`)
      )
    );
  }

  await i18nInstance.init({
    lng: locale,
    resources: options?.resources,
    fallbackLng: i18nConfig.defaultLocale,
    supportedLngs: i18nConfig.locales,
    defaultNS: namespaces[0],
    fallbackNS: namespaces[0],
    ns: namespaces,
    preload: options?.resources ? [] : i18nConfig.locales,
  });

  return {
    i18n: i18nInstance,
    resources: i18nInstance.services.resourceStore.data,
    t: i18nInstance.getFixedT(
      locale,
      namespaces[0],
      options?.keyPrefix
    ) as TFunction<Locale, undefined>,
  };
}

// Exported function to fetch translations on server components
export async function serverSideTranslation(
  locale: string,
  namespaces: string[],
  options?: { keyPrefix?: string; i18nInstance?: any; resources?: any }
) {
  return await initTranslations(locale, namespaces, options);
}

Step 2: Consuming Translations in Server Components

To use these translations in your server components, for example inside home page (src/app/[locale]/page.tsx)

import { serverSideTranslation } from "@/lib/i18n";

type Props = {
  params: Promise<{ locale: string }>
}

export default async function Page({ params }: Props) {
  const {locale} = await params
  const ns = ["home"]; // namespace used for this page
  const { t } = await serverSideTranslation(locale, ns);

  return (
    <div>
      <h1>{t("welcome")}</h1>
      <p>{t("description")}</p>
    </div>
  );
}

Explanation:

locale: Comes directly from the dynamic route params ([locale]).
ns: The namespace corresponds to the JSON translation file (home.json).
t: Translation function returned from serverSideTranslation.

Client-side Internationalization (i18n)

Why Send Translations to the Client?

In Next.js App Router, translations are loaded server-side by default. However, your client-side components (interactive components, buttons, inputs, etc.) also need access to translations. To achieve this, you'll pass translations from the server to the client via a wrapper provider.

Step 1: Create the Client-side Translation Provider

Create a wrapper component (I18NProvider) that passes translations from server-side to client-side components:

Create new file src/components/i18n/i18n-provider.tsx

"use client";

import { I18nextProvider } from "react-i18next";
import { createInstance } from "i18next";
import { serverSideTranslation } from "@/lib/i18n";

type Props = {
  children: React.ReactNode;
  locale: string;
  namespaces: string[];
  resources: any;
};

export default function I18NProvider({
  children,
  locale,
  namespaces,
  resources,
}: Props) {
  const i18n = createInstance();

  // Initialize client-side i18n instance with resources provided by the server
  serverSideTranslation(locale, namespaces, { i18nInstance: i18n, resources });

  return (
    <I18nextProvider i18n={i18n}>
      {children}
    </I18nextProvider>
  );
}

Explanation:

Uses createInstance() from i18next to initialize a new client-side i18n instance.
Reuses server-loaded translations by passing resources directly to the client, avoiding extra client-side fetches.

Step 2: Wrap Your Client Components

In your server components (or page, layouts), wrap your client-side tree using the I18NProvider created above:

import { serverSideTranslation } from "@/lib/i18n";
import ClientComponent from "./client-component"

type Props = {
  params: Promise<{ locale: string }>
}

export default async function Page({ params }: Props) {
  const {locale} = await params
  const ns = ["home"]; // namespace used for this page
  const { t } = await serverSideTranslation(locale, ns);

  return (
    <div>
      <h1>{t("welcome")}</h1>
      <p>{t("description")}</p>
      
      <I18NProvider locale={locale} namespaces={ns} resources={resources}>
        <ClientComponent />
      </I18NProvider>
    </div>
  );
}

Explanation:

Page fetches translations server-side via serverSideTranslation.
Passes resources and locale to the client-side via the I18NProvider.

Step 3: Consuming Translations in Client Components

Once wrapped, any client-side component can easily access translations using the familiar useTranslation hook:

But, first add some translation strings to;

translations/en/home.json

{
  "welcome": "Welcome",
  "description": "This is an English description.",
  "client-component": {
    "heading": "This is client component"
  }
}

translations/ar/home.json

{
  "welcome": "مرحبا",
  "description": "هذا وصف باللغة العربية.",
  "client-component": {
    "heading": "هذا هو مكون العميل"
  }
}

Now let's use translations inside client component (src/app/[locale]/client-component.tsx).

"use client";

import { useTranslation } from "react-i18next";

export default function ClientComponent() {
  const { t } = useTranslation("home", {
    keyPrefix: "content.client-component"
  });

  return (
    <div>
      <h2>{t("heading")}</h2>
    </div>
  );
}

Explanation:

Simply imports useTranslation hook.
Uses the same keys defined in your translation JSON (home.json).

Locale Switcher

To allow users to switch between languages on the client side, you'll implement a locale switcher component. This component updates the language preference, persists it in a cookie, and redirects the user to the correct localized route.

src/components/i18n/locale-switch.tsx

"use client";

import React from "react";
import { usePathname, useRouter } from "next/navigation";
import { useTranslation } from "react-i18next";
import { i18nConfig } from "@/lib/i18n";

export default function LocaleSwitch() {
  const { i18n } = useTranslation();
  const activeLocale = i18n.language;

  const router = useRouter();
  const currentPathname = usePathname();

  const onLanguageChange = () => {
    const newLocale = activeLocale === "en" ? "ar" : "en";

    // Set a cookie for next-i18n-router to read the new locale
    const days = 30;
    const date = new Date();
    date.setTime(date.getTime() + days * 24 * 60 * 60 * 1000);
    const expires = date.toUTCString();
    document.cookie = `NEXT_LOCALE=${newLocale};expires=${expires};path=/`;

    // Compute new path with updated locale
    if (activeLocale === i18nConfig.defaultLocale && !i18nConfig.prefixDefault) {
      router.push("/" + newLocale + currentPathname);
    } else {
      router.push(currentPathname.replace(`/${activeLocale}`, `/${newLocale}`));
    }

    router.refresh();
  };

  return (
    <div className="widget language-switch-widget">
      <button
        className="w-auto cursor-pointer bg-transparent"
        onClick={onLanguageChange}
      >
          {activeLocale === "en" ? "عربي" : "English"}
      </Button>
    </div>
  );
}

Now you can simply render this anywhere inside your app. Don't forget to wrap it inside I18NProvider - for example if you are rendering it inside root layout (src/app/[locale]/layout.tsx).

import { getDirection } from "@/lib/utils";
import { Locale } from "@/lib/types";
import LocaleSwitch from "@/components/i18n/locale-switch";
import I18NProvider from "@/components/i18n/translations-provider";

type RootLayoutProps = {
  children: React.ReactNode;
  params: Promise<{ locale: Locale }>;
};

export default async function RootLayout({
  children,
  params,
}: RootLayoutProps) {
  const { locale } = await params;
  return (
    <html lang={locale} dir={getDirection(locale)}>
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased relative`}
      >
        {/* pass locale to client-side i18n provider */}
        <I18NProvider locale={locale} namespaces={[]} resources={[]}>
            {children}
            <LocaleSwitch />
        </I18NProvider>
      </body>
    </html>
  );
}

Conclusion

You're now fully equipped to build a multilingual Next.js 15+ App Router application with i18next!

See you in next one.

Implementing i18n in Next.js 15 (App) using i18next

Azhar Zaman

Initial Setup & Middleware Configuration

Step 1: Create a new Next.js App

Installing Dependencies

Step 2: Add a Dynamic Locale Route

Step 3: Create an i18n Configuration File

Step 4: Middleware Setup for Locale Route Handling

Step 5: Set lang and dir inside Root Layout

Step 6: Add translations

Server side Internationalization (i18n)

Step 1: Create Server-side Translation Utility

Step 2: Consuming Translations in Server Components

Client-side Internationalization (i18n)

Why Send Translations to the Client?

Step 1: Create the Client-side Translation Provider

Step 2: Wrap Your Client Components

Step 3: Consuming Translations in Client Components

Locale Switcher

Conclusion

Step 5: Set `lang` and `dir` inside Root Layout