The Complete Guide to Next.js Internationalization

Set up next-intl with the App Router, configure locale routing, and automate translations with AI.

1

marketing.seo.nextjsI18n.guide.installTitle

marketing.seo.nextjsI18n.guide.installDescription

Terminal
npm install next-intl
2

2. Configure Middleware for Locale Routing

Add middleware to handle locale detection and routing.

middleware.ts
import createMiddleware from 'next-intl/middleware';

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

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)']
};
3

3. Set Up Message Files

Create JSON message files per locale and configure the i18n request handler.

messages/en.json
// messages/en.json
{
  "HomePage": {
    "title": "Welcome to our app",
    "description": "Build multilingual Next.js apps with ease"
  },
  "Navigation": {
    "home": "Home",
    "about": "About",
    "contact": "Contact"
  }
}
4

4. Update Your Layout

Pass locale and messages to NextIntlClientProvider in your root layout.

app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';

export default async function LocaleLayout({
  children,
  params
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const messages = await getMessages();

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

5. Use Translations in Components

Use useTranslations in client components and getTranslations in server components.

app/[locale]/page.tsx
// Client Component
'use client';
import { useTranslations } from 'next-intl';

export default function HomePage() {
  const t = useTranslations('HomePage');
  return <h1>{t('title')}</h1>;
}

// Server Component
import { getTranslations } from 'next-intl/server';

export default async function AboutPage() {
  const t = await getTranslations('AboutPage');
  return <h1>{t('title')}</h1>;
}
6

6. Automate with i18n Agent

With your i18n setup complete, automate translation of your message files directly from your IDE.

Terminal
# In your IDE, ask your AI assistant:
> Translate messages/en.json to German, Japanese, and Spanish

✓ messages/de.json created (1.1s)
✓ messages/ja.json created (1.4s)
✓ messages/es.json created (1.0s)

Try i18n Agent Now

Drop your translation file here

JSON, YAML, PO, XML, CSV, Markdown, Properties

or click to browse

Target languages

No signup requiredInstant estimate

Frequently Asked Questions