{"id":6851,"date":"2025-10-20T06:00:00","date_gmt":"2025-10-20T06:00:00","guid":{"rendered":"https:\/\/poeditor.com\/blog\/?p=6851"},"modified":"2026-04-20T12:51:04","modified_gmt":"2026-04-20T12:51:04","slug":"next-js-i18n","status":"publish","type":"post","link":"https:\/\/poeditor.com\/blog\/next-js-i18n\/","title":{"rendered":"Next.js i18n with next-intl: A comprehensive guide"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

Next.js is one of the popular ways to ship React<\/a> apps today. It\u2019s fast, it scales, and it\u2019s straightforward. A lot of us use it for documentation sites, dashboards, storefronts, and marketing pages because it covers both developer ergonomics and production needs.<\/p>\n\n\n\n

When you\u2019re building for more than one market, it\u2019s expected that your app speaks the user\u2019s language. That means you need to implement internationalization (i18n) and localization (l10n).<\/p>\n\n\n\n

In this guide, we\u2019ll set up i18n in a Next.js app using next-intl. We\u2019ll explain how to set it up for both the App and Pages Router.<\/p>\n\n\n\n

Getting started<\/h2>\n\n\n\n

To follow this guide, you need a Next.js app. If you don\u2019t have one yet, create it with:<\/p>\n\n\n\n

npx create-next-app@latest [project-name]<\/code><\/p>\n\n\n\n

During the prompts, you can pick App Router<\/strong> or Pages Router<\/strong> depending on your preference. If you already have an app, just note which router you\u2019re using.<\/p>\n\n\n\n

Once the project is up, install next-intl<\/code><\/a>:<\/p>\n\n\n\n

npm i next-intl<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

npm i next-intl<\/code><\/p>\n\n\n\n

You may ask, why next-intl<\/a>? Fair question. Next.js already has solid i18n routing, and next-intl<\/code> sits nicely on top of it. It covers the essentials you actually need such as interpolation, pluralization, arrays, and more using ICU messages. It also works with both App Router and Pages Router, so you\u2019re not boxed in.<\/p>\n\n\n\n

With next-intl<\/code> installed, we\u2019re good to go.<\/p>\n\n\n\n

Set up i18n for App Router (step-by-step)<\/h2>\n\n\n\n

For internationalization to work in your app, the first thing to do is add the next-intl<\/code> plugin to Next.js. Open the next.config.ts<\/code> file and replace it with this or adjust it to use this:<\/p>\n\n\n\n

\/\/ next.config.ts
import createNextIntlPlugin from 'next-intl\/plugin';
const withNextIntl = createNextIntlPlugin();

\/** @type {import('next').NextConfig} *\/
const nextConfig = {};

export default withNextIntl(nextConfig);<\/code><\/p>\n\n\n\n

What this does is that it wraps your Next.js config so next-intl<\/code> can plug into the build and server runtime. Under the hood, the plugin looks for a \u201crequest config\u201d (we\u2019ll add it next) to know which messages file to load for each locale.<\/p>\n\n\n\n

The next step is to declare your locales and set up a couple of helpers for navigation. For separation of concerns, it makes sense to keep i18n stuff in its own folder, so create src\/i18n\/<\/code> and then add routing.ts<\/code>:<\/p>\n\n\n\n

\/\/ src\/i18n\/routing.ts
import {createSharedPathnamesNavigation} from 'next-intl\/navigation';

export const locales = ['en', 'de'] as const;
export type Locale = (typeof locales)[number];

export const defaultLocale: Locale = 'en';

\/**
* These helpers are drop-in replacements for Next's Link\/useRouter etc,
* but they keep the locale in the URL automatically.
*\/
export const {Link, redirect, usePathname, useRouter} =
  createSharedPathnamesNavigation({
    locales,
    \/\/ 'always' -> URLs are always prefixed (\/en, \/de)
    \/\/ If you prefer \/ (no prefix) for default locale, use 'as-needed'
    localePrefix: 'always'
  });<\/code><\/p>\n\n\n\n

This helps you declare supported languages and a default in one place. From here on, the locale-aware Link<\/code> and router hooks keep \/en<\/code> or \/de<\/code> in your paths automatically.<\/p>\n\n\n\n

Now, you need to tell next-intl<\/code> how to load messages for each request. In the same src\/i18n\/<\/code> folder, create request.ts<\/code>:<\/p>\n\n\n\n

\/\/ src\/i18n\/request.ts
import {getRequestConfig} from 'next-intl\/server';
import {locales, defaultLocale, type Locale} from '.\/routing';<\/code>

\/**
* This runs on the server for each request.
* It validates the incoming locale and dynamically loads the right JSON file.
*\/
export default getRequestConfig(async ({locale}) => {
  const isSupported = locales.includes(locale as Locale);
  const resolvedLocale = (isSupported ? locale : defaultLocale) as Locale;

  const messages = (await import(`..\/..\/messages\/${resolvedLocale}.json`)).default;

  return {
    locale: resolvedLocale,
    messages
  };
});<\/code><\/p>\n\n\n\n

What this does is that the plugin you added in next.config.ts<\/code> calls this to figure out which JSON to load based on the URL. It\u2019s dynamic, so you only pull in what you actually need.<\/p>\n\n\n\n

As the final core file needed for the setup, you need a small middleware<\/a> to keep URLs locale-aware and to bump \/<\/code> to your default locale (\/en<\/code> in this example). Create src\/middleware.ts<\/code>:<\/p>\n\n\n\n

\/\/ src\/middleware.ts
import createMiddleware from 'next-intl\/middleware';
import {locales, defaultLocale} from '.\/i18n\/routing';

export default createMiddleware({
  locales,
  defaultLocale,
  localePrefix: 'always',
  \/\/ Keep behavior deterministic (no automatic browser-language redirects).
  localeDetection: false
});

export const config = {
  \/**
  * Apply middleware to the homepage and any path that already has a locale prefix.
  * Adjust the matcher if you add more locales.
  *\/
  matcher: ['\/', '\/(en|de)\/:path*']
};<\/code><\/p>\n\n\n\n

This makes sure every route is prefixed with a locale (e.g., \/en<\/code>, \/de<\/code>). Visiting \/ redirects to \/${defaultLocale}<\/code>, so \/ \u2192 \/en<\/code>. Browser-language detection is turned off to avoid surprise redirects during development. You can enable it if that\u2019s your preference.<\/p>\n\n\n\n

Add your translation files<\/h3>\n\n\n\n

Localization works by resolving keys to messages per locale. The clean way to manage this is to keep one JSON per language. At your project root, create a messages\/<\/code> folder and add two files with the same keys in both.<\/p>\n\n\n\n

messages\/en.json:<\/code><\/p>\n\n\n\n

{
\"Home\": {
\"title\": \"Welcome\",
\"greeting\": \"Welcome back, {name}!\"
}
}<\/code><\/p>\n\n\n\n

messages\/de.json<\/code><\/p>\n\n\n\n

{
\"Home\": {
\"title\": \"Willkommen\",
\"greeting\": \"Willkommen zur\u00fcck, {name}!\"
}
}<\/code><\/p>\n\n\n\n

Keep the keys identical across locales (Home.title<\/code>, Home.greeting<\/code>, etc.). This is how tools (and people) keep translations in sync. We\u2019ll connect this to POEditor<\/a> later. For now, local JSON keeps the flow simple.<\/p>\n\n\n\n

Update app structure<\/h3>\n\n\n\n

Next.js App Router uses a segment for the locale, so we\u2019ll route everything through \/[locale]\/\u2026<\/code>. First, let\u2019s make the root page nudge users to the default locale. Open src\/app\/page.tsx<\/code> and add:<\/p>\n\n\n\n

import { redirect } from 'next\/navigation';

\/\/ This page only renders when the app is built statically (output: 'export')
export default function RootPage() {
redirect('\/en');
}<\/code><\/p>\n\n\n\n

Now create a [locale]<\/code> folder under src\/app\/<\/code> and add a layout.tsx<\/code>. This layout is a Server Component<\/a> that validates the locale, loads the correct messages, and provides them to everything below:

\/\/ src\/app\/[locale]\/layout.tsx
import {NextIntlClientProvider} from 'next-intl';
import {notFound} from 'next\/navigation';
import {locales, type Locale} from '@\/i18n\/routing';
<\/code>
export default async function LocaleLayout({
  children,
params: {locale}
}: {
  children: React.ReactNode;
  params: {locale: string};
}) {
  \/\/ Validate the URL param
  if (!locales.includes(locale as Locale)) notFound();
<\/code>
\/\/ Load messages for this locale
  const messages = (await import(`..\/..\/..\/messages\/${locale}.json`)).default;
<\/code><\/p>\n\n\n\n

return (
    <html lang={locale}>
      <body>
        {\/* Make messages available to all client components below *\/}
        <NextIntlClientProvider locale={locale} messages={messages}>
          {children}
        <\/NextIntlClientProvider>
      <\/body>
    <\/html>
  );
}<\/code><\/p>\n\n\n\n

What happens in the code above is that <html lang={locale}><\/code> helps browsers, assistive tech, and SEO understand the language. NextIntlClientProvider<\/code> exposes messages to client components via hooks.<\/p>\n\n\n\n

Render a page that uses translations<\/h3>\n\n\n\n

Inside the same [locale]<\/code> folder, add page.tsx. This one is a client component so we can use the useTranslations<\/code> hook:<\/p>\n\n\n\n

\/\/ src\/app\/[locale]\/page.tsx
'use client';

import {useTranslations} from 'next-intl';

export default function HomePage() {
  const t = useTranslations('Home');
  const name = 'Jane';<\/code><\/p>\n\n\n\n


return (
    <main style={{padding: 24}}>
      <h1>{t('title')}<\/h1>
      <p>{t('greeting', {name})}<\/p>
    <\/main>
  );
}<\/code><\/p>\n\n\n\n

That\u2019s it! Keys from messages\/{locale}.json<\/code> flow into the component, and next-intl handles formatting and interpolation. Hooks like useTranslations<\/code> run in client components, the layout stays server-side.<\/p>\n\n\n\n

Add a language switcher<\/h3>\n\n\n\n

Before we jump to the Pages Router, let\u2019s make switching languages easy. Create src\/components\/Navigation.tsx<\/code>:<\/p>\n\n\n\n

\/\/ src\/components\/Navigation.tsx
'use client';

import {Link, usePathname} from '@\/i18n\/routing';

export default function Navigation() {
  const pathname = usePathname();

  return (
    <nav style={{display: 'flex', gap: 12, padding: 16}}>
      {\/* Link\/Path helpers keep the current path but swap the locale *\/}
      <Link href={pathname} locale=\"en\">EN<\/Link>
      <Link href={pathname} locale=\"de\">DE<\/Link>
    <\/nav>
  );
}<\/code><\/p>\n\n\n\n

Drop <Navigation \/><\/code> anywhere under [locale]\/layout.tsx<\/code> or inside your page. Now you can hop between \/en<\/code> and \/de<\/code> without losing the current route.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

You can access the complete project in this GitHub repository<\/a> to compare the setup. Here is what the final file structure should look like:<\/p>\n\n\n\n

your-app\/
\u251c\u2500 next.config.ts
\u251c\u2500 messages\/
\u2502  \u251c\u2500 en.json
\u2502  \u2514\u2500 de.json
\u251c\u2500 src\/
\u2502  \u251c\u2500 i18n\/
\u2502  \u2502  \u251c\u2500 request.ts
\u2502  \u2502  \u2514\u2500 routing.ts
\u2502  \u251c\u2500 middleware.ts
\u2502  \u251c\u2500 app\/
\u2502  \u2502  \u251c\u2500 page.tsx                # (optional) redirects \"\/\" \u2192 \"\/en\"
\u2502  \u2502  \u2514\u2500 [locale]\/
\u2502  \u2502     \u251c\u2500 layout.tsx           # loads messages + wraps provider
\u2502  \u2502     \u2514\u2500 page.tsx             # uses translations in a client component
\u2502  \u2514\u2500 components\/
\u2502     \u2514\u2500 Navigation.tsx          # language switcher (EN\/DE)
\u2514\u2500 package.json
<\/code><\/p>\n\n\n\n

Set up i18n for Pages Router (step-by-step)<\/h2>\n\n\n\n

If you\u2019re on the Pages Router, the flow is a little different from App Router. We won\u2019t use a [locale]<\/code> segment, instead we\u2019ll lean on Next.js built-in i18n routing<\/a> (\/en<\/code>, \/de<\/code>, etc.), connect it with next-intl<\/code> once in _app.tsx<\/code>, and load messages per page with getStaticProps<\/code> (or getServerSideProps<\/code> if you prefer SSR<\/a>).<\/p>\n\n\n\n

To get started, you need to tell Next.js which locales you support and wrap your config with the next-intl<\/code> plugin. Open next.config.ts<\/code> and adjust it:<\/p>\n\n\n\n

\/\/ next.config.ts
import createNextIntlPlugin from 'next-intl\/plugin';

const withNextIntl = createNextIntlPlugin();

\/** @type {import('next').NextConfig} *\/
const nextConfig = {
  \/\/ Next.js built-in i18n does the URL routing for Pages Router
  i18n: {
    locales: ['en', 'de'],
    defaultLocale: 'en',
    \/\/ You can flip this to true later if you want auto language detection
    localeDetection: false
  }
};

export default withNextIntl(nextConfig);<\/code><\/p>\n\n\n\n

Next, create a \u201crequest config\u201d so the plugin knows where to fetch messages. Make a folder src\/i18n\/<\/code> and add request.ts<\/code>:<\/p>\n\n\n\n

\/\/ src\/i18n\/request.ts
import {getRequestConfig} from 'next-intl\/server';
<\/code><\/p>\n\n\n\n

export default getRequestConfig(async ({locale}) => {
\/\/ Guard against unexpected locales; fall back to 'en'
const supported = ['en', 'de'] as const;
const isSupported = (supported as readonly string[]).includes(locale);
const resolved = isSupported ? locale : 'en';
<\/code><\/p>\n\n\n\n

const messages = (await import(..\/..\/messages\/${resolved}.json)).default;
return {locale: resolved, messages};
});<\/code><\/p>\n\n\n\n


What this does is that whenever a request comes in for \/de\/...<\/code>, the plugin calls this, we validate the locale, and we import the right JSON file. It\u2019s dynamic, so you only load what you need.<\/p>\n\n\n\n

Now add your translation files. Just like we did for App Router, keep one JSON per locale with the same keys.<\/p>\n\n\n\n

\/messages
  \u251c\u2500 en.json
  \u2514\u2500 de.json<\/code><\/p>\n\n\n\n

Next, add the provider once at the top of your app so every page can read translations. Create src\/pages\/_app.tsx<\/code>:<\/p>\n\n\n\n

\/\/ src\/pages\/_app.tsx
import type {AppProps} from 'next\/app';
import {NextIntlProvider} from 'next-intl';

type Messages = Record<string, unknown>;

export default function MyApp({
  Component,
  pageProps
}: AppProps & {pageProps: {messages?: Messages; locale?: string}}) {
  const {messages, locale} = pageProps;

  \/\/ In dev you might navigate to a page before messages are loaded; guard it.
  if (!messages || !locale) {
    return <Component {...pageProps} \/>;
  }

  return (
    <NextIntlProvider messages={messages} locale={locale}>
      <Component {...pageProps} \/>
    <\/NextIntlProvider>
  );
}<\/code><\/p>\n\n\n\n

This is important because _app.tsx<\/code> is the Pages Router\u2019s global shell. Wrapping with NextIntlProvider<\/code> here means any component can grab translations with useTranslations<\/code>.<\/p>\n\n\n\n

Now load messages per page. For the homepage, create src\/pages\/index.tsx<\/code>:<\/p>\n\n\n\n

\/\/ src\/pages\/index.tsx
import {useTranslations} from 'next-intl';
import type {GetStaticPropsContext, InferGetStaticPropsType} from 'next';

export default function HomePage(
  _props: InferGetStaticPropsType<typeof getStaticProps>
) {
  const t = useTranslations('Home');
  const name = 'Jane';
  const count = 3;

  return (
    <main style={{padding: 24}}>
      <h1>{t('title')}<\/h1>
      <p>{t('greeting', {name})}<\/p>
      <p>{t('inbox', {count})}<\/p>
    <\/main>
  );
}

\/\/ SSG example; use getServerSideProps if your content is request-time
export async function getStaticProps({locale}: GetStaticPropsContext) {
  const messages = (await import(`..\/..\/messages\/${locale}.json`)).default;
  return {
    props: {
      messages,
      locale
    }
  };
}<\/code><\/p>\n\n\n\n

What\u2019s happening here is that:<\/p>\n\n\n\n