next-intl

In this article, you will learn how to integrate next-intl with Next.js and manage your translations using SimpleLocalize. next-intl is a modern internationalization library for Next.js, supporting both App Router and Pages Router. This guide uses Next.js 14+, React 18, and next-intl 3.x.

Installation

Install next-intl for Next.js:

npm install next-intl

Configuration

Create a messages directory for your translation files, e.g. /messages/{locale}.json.

Example file structure:

/messages
  en.json
  es.json
  fr.json
  pl.json

Each file contains translations for a specific language:

// messages/en.json
{
  "HELLO_WORLD": "Hello World!",
  "LEARN_MORE": "Learn more"
}

Setup in Next.js

App Router

Wrap your app with the NextIntlClientProvider in app/layout.tsx:

import {NextIntlClientProvider} from 'next-intl';
import messages from '../messages/en.json';

export default function RootLayout({children}) {
  return (
    <html lang="en">
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

To support multiple locales, load the correct messages file based on the current locale.

Pages Router

Wrap your app in _app.tsx:

import {NextIntlProvider} from 'next-intl';
import messages from '../messages/en.json';

function MyApp({Component, pageProps}) {
  return (
    <NextIntlProvider messages={messages}>
      <Component {...pageProps} />
    </NextIntlProvider>
  );
}

export default MyApp;

Usage

Use the useTranslations hook to access translations in your components:

import {useTranslations} from 'next-intl';

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

Language Switcher

To switch languages, you can use Next.js routing:

import Link from 'next/link';

export default function LanguageSwitcher() {
  return (
    <div>
      <Link href="/" locale="en">English</Link>
      <Link href="/" locale="es">Spanish</Link>
      <Link href="/" locale="fr">French</Link>
      <Link href="/" locale="pl">Polish</Link>
    </div>
  );
}

Interpolation and Plurals

next-intl supports interpolation and pluralization:

{
  "GREET_USER": "Hello {name}!",
  "MESSAGES": "{count} {count, plural, one {message} other {messages}}"
}

const t = useTranslations();
t('GREET_USER', {name: 'Jakub'}); // Hello Jakub!
t('MESSAGES', {count: 1}); // 1 message
t('MESSAGES', {count: 5}); // 5 messages

Managing translation files

To manage your translations in the SimpleLocalize translation editor, use the SimpleLocalize CLI.

Configuration

Create a simplelocalize.yml file in your project root:

apiKey: YOUR_PROJECT_API_KEY
uploadFormat: single-language-json
uploadLanguageKey: en
uploadPath: ./messages/en.json
uploadOptions:
  - REPLACE_TRANSLATION_IF_FOUND

downloadFormat: single-language-json
downloadLanguageKeys: ['pl', 'fr', 'es']
downloadPath: ./messages/{lang}.json

Upload translations

simplelocalize upload

Download translations

simplelocalize download

This guide should help you get started with next-intl and SimpleLocalize in your Next.js project!

Was this helpful?