How to Add i18n to Next.js: Simple Setup Guide

To add i18n in Next.js, configure the i18n field in next.config.js with your supported locales and default locale. For easier translation management, use the next-i18next library which integrates with Next.js and React hooks for translations.

Syntax

Next.js supports i18n by configuring the i18n object in next.config.js. This object includes:

• locales: an array of language codes your app supports.
• defaultLocale: the default language shown when no locale is specified.

Example configuration:

javascript

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'es'],
    defaultLocale: 'en',
  },
};

Example

This example shows how to set up next-i18next for translations in a Next.js app. It includes configuration, translation files, and usage in a component.

javascript

// next.config.js
const { i18n } = require('./next-i18next.config');

module.exports = {
  i18n,
};

// next-i18next.config.js
module.exports = {
  i18n: {
    locales: ['en', 'fr'],
    defaultLocale: 'en',
  },
};

// public/locales/en/common.json
{
  "greeting": "Hello!"
}

// public/locales/fr/common.json
{
  "greeting": "Bonjour!"
}

// pages/_app.js
import { appWithTranslation } from 'next-i18next';

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

export default appWithTranslation(MyApp);

// pages/index.js
import { useTranslation } from 'next-i18next';
import { serverSideTranslations } from 'next-i18next/serverSideTranslations';

export default function Home() {
  const { t } = useTranslation('common');
  return <h1>{t('greeting')}</h1>;
}

export async function getStaticProps({ locale }) {
  return {
    props: {
      ...(await serverSideTranslations(locale, ['common'])),
    },
  };
}

Output

<h1>Hello!</h1> (when locale is 'en') or <h1>Bonjour!</h1> (when locale is 'fr')

Common Pitfalls

• Missing locale files: Forgetting to add translation JSON files for each locale causes errors or missing text.
• Not wrapping _app.js: Omitting appWithTranslation wrapper prevents translations from loading.
• Incorrect locale keys: Using wrong keys in useTranslation or missing namespaces leads to empty strings.
• Not configuring next.config.js properly: The i18n field must be present and correct for Next.js routing to work with locales.

javascript

// Wrong: missing appWithTranslation wrapper
// pages/_app.js
function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;

// Right: with appWithTranslation
import { appWithTranslation } from 'next-i18next';

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

export default appWithTranslation(MyApp);

Quick Reference

• next.config.js: Add i18n with locales and defaultLocale.
• Translation files: Place JSON files under public/locales/[locale].
• Use next-i18next: Wrap _app.js with appWithTranslation and use useTranslation hook.
• Load translations server-side: Use serverSideTranslations in getStaticProps or getServerSideProps.

Key Takeaways

Configure the i18n object in next.config.js with your locales and defaultLocale.

Use next-i18next for easy translation management and React hooks support.

Always wrap your _app.js with appWithTranslation to enable translations.

Place translation JSON files in public/locales/[locale] folders.

Load translations server-side using serverSideTranslations in data fetching methods.