Next.js & Internationalization: A Beginner’s Guide

Written by

learnmodernwebdevelopment

in

In today’s interconnected world, reaching a global audience is more critical than ever. Imagine building a website for your business, a blog, or an application, and having users from different countries stumble upon it. Wouldn’t it be fantastic if your website could automatically adapt to their preferred language, offering a seamless and personalized experience? This is where internationalization (i18n) comes in, and Next.js provides powerful tools to make it a breeze. This tutorial will walk you through the fundamentals of i18n in Next.js, equipping you with the knowledge to create multilingual websites that resonate with users worldwide.

Why Internationalization Matters

Before diving into the code, let’s understand why i18n is so crucial. Consider the following scenarios:

  • Improved User Experience: Imagine landing on a website in a language you don’t understand. Frustrating, right? i18n ensures users see content in their native language, significantly enhancing their experience and making them more likely to engage with your site.
  • Increased Reach and Engagement: By catering to a global audience, you broaden your potential user base. Offering content in multiple languages can lead to higher traffic, increased conversions, and a stronger brand presence.
  • Enhanced SEO: Search engines like Google prioritize websites that provide content in the user’s language. Implementing i18n correctly can improve your search rankings in different regions.
  • Compliance: In some regions, providing content in the local language is a legal requirement. i18n helps you meet these compliance standards.

In essence, i18n is about making your website accessible and user-friendly for everyone, regardless of their language. Next.js simplifies this process, allowing you to focus on creating great content and experiences.

Setting Up Your Next.js Project

If you don’t already have a Next.js project, let’s create one. Open your terminal and run the following command:

npx create-next-app my-i18n-app --typescript

This command creates a new Next.js project named “my-i18n-app” with TypeScript support. Navigate into your project directory:

cd my-i18n-app

Now, let’s install the necessary packages for i18n. We’ll be using the `next-i18next` library, which is a popular and well-maintained solution for Next.js i18n:

npm install next-i18next i18next react-i18next

These packages provide the core functionalities for managing translations, detecting user locales, and rendering translated content.

Configuring i18next

The next step is to configure `i18next`. Create a new folder named `i18n` in the root of your project. Inside this folder, create a file named `i18n.ts` (or `i18n.js` if you’re not using TypeScript) and add the following code:

import { initReactI18next } from 'react-i18next';
import i18n from 'i18next';

// Import your translation files (see below)
import en from './locales/en/translation.json';
import fr from './locales/fr/translation.json';

const resources = {
  en: {
    translation: en,
  },
  fr: {
    translation: fr,
  },
};

i18n.use(initReactI18next).init({
  resources,
  lng: 'en', // Default language
  fallbackLng: 'en', // Fallback language if translation is missing
  interpolation: {
    escapeValue: false, // React already does escaping
  },
});

export default i18n;

Let’s break down this configuration:

  • Import Statements: We import necessary modules from `react-i18next` and `i18next`.
  • Translation Files: We import our translation files. We’ll create these files shortly.
  • Resources: The `resources` object maps language codes (e.g., ‘en’, ‘fr’) to their respective translation files.
  • `i18n.init` Configuration:
    • `resources`: The translation resources.
    • `lng`: The default language of your website (e.g., ‘en’ for English).
    • `fallbackLng`: The language to use if a translation is missing for the current language.
    • `interpolation`: This setting disables HTML escaping, as React handles it automatically.

Creating Translation Files

Next, we need to create the translation files. Inside the `i18n` folder, create a new folder named `locales`. Within the `locales` folder, create subfolders for each language you want to support (e.g., `en`, `fr`). Inside each language folder, create a file named `translation.json` (or any name you prefer). For example:

i18n/locales/en/translation.json:

{
  "welcome": "Welcome to our website!",
  "about_us": "About Us",
  "contact_us": "Contact Us",
  "home": "Home",
  "language": "Language",
  "change_language": "Change Language to {{lng}}"
}

i18n/locales/fr/translation.json:

{
  "welcome": "Bienvenue sur notre site web !",
  "about_us": "À propos de nous",
  "contact_us": "Contactez-nous",
  "home": "Accueil",
  "language": "Langue",
  "change_language": "Changer la langue en {{lng}}"
}

These JSON files store the translations for your website’s text. Make sure to include all the keys you will use in your app, and translate their values accordingly. The `{{lng}}` in “change_language” is a placeholder that will be replaced with the selected language code.

Using Translations in Your Components

Now, let’s use the translations in your Next.js components. Import the `useTranslation` hook from `react-i18next` and use it to access the translations.

pages/index.tsx:

import { useTranslation } from 'react-i18next';
import Link from 'next/link';

function HomePage() {
  const { t, i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('about_us')}</p>
      {t('contact_us')}
      <p>{t('change_language', { lng: i18n.language })}</p>
      <button> changeLanguage(i18n.language === 'en' ? 'fr' : 'en')}>
        {t('language')}: {i18n.language}
      </button>
    </div>
  );
}

export default HomePage;

Let’s break down this example:

  • `useTranslation()`: This hook provides access to the `t` function (for translating text) and the `i18n` object (for language-related operations).
  • `t(‘key’)`: The `t` function retrieves the translation for the specified key from your translation files. For example, `t(‘welcome’)` will return “Welcome to our website!” in English or “Bienvenue sur notre site web !” in French, depending on the current language.
  • `i18n.language`: This property holds the current language code (e.g., ‘en’, ‘fr’).
  • `i18n.changeLanguage(lng)`: This function changes the current language.

In this example, we’re displaying the “welcome”, “about_us”, and “contact_us” translations. We are also adding a button to switch languages.

Create a contact page, `pages/contact.tsx`, to see how the translations work on other pages:

import { useTranslation } from 'react-i18next';

function ContactPage() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t('contact_us')}</h1>
      <p>This is the contact page.</p>
    </div>
  );
}

export default ContactPage;

Setting Up the i18n Configuration in Next.js

To integrate `next-i18next` with your Next.js application, you need to configure it in `next.config.js`. If you don’t have this file, create it in the root directory of your project.

next.config.js:

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

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  i18n,
}

module.exports = nextConfig;

Create `next-i18next.config.js` to store the i18n configuration:

/** @type {import('next-i18next').UserConfig} */
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },
}

Let’s break down these configurations:

  • `defaultLocale`: Defines the default language for your application.
  • `locales`: An array of all the locales your application supports.

With these configurations, Next.js will use `next-i18next` to handle routing and translation-related functionalities.

Implementing Language Switching

The code in `pages/index.tsx` already includes a basic language-switching mechanism. Let’s explore more advanced strategies:

1. Using a Language Selector Component

Create a reusable component for selecting the language. This keeps your components cleaner and more maintainable.

components/LanguageSelector.tsx:

import { useTranslation } from 'react-i18next';

interface LanguageSelectorProps {
  onChange: (lng: string) => void;
  currentLanguage: string;
}

function LanguageSelector({ onChange, currentLanguage }: LanguageSelectorProps) {
  const { t } = useTranslation();

  return (
    <div>
      <label>{t('language')}: </label>
       onChange(e.target.value)}
      >
        English
        Français
      
    </div>
  );
}

export default LanguageSelector;

In this component, we use a select element to allow the user to choose their preferred language. The `onChange` prop is a function that is called when the user selects a different language. The `currentLanguage` prop displays the current language.

Update your `pages/index.tsx` to use the new component:

import { useTranslation } from 'react-i18next';
import Link from 'next/link';
import LanguageSelector from '../components/LanguageSelector';

function HomePage() {
  const { t, i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('about_us')}</p>
      {t('contact_us')}
      
    </div>
  );
}

export default HomePage;

2. Using the `next/router` for Routing

When the language changes, you might also want to update the URL to reflect the selected language. `next-i18next` provides built-in support for this through the `useRouter` hook. Update the `HomePage` as follows:

import { useTranslation } from 'react-i18next';
import Link from 'next/link';
import { useRouter } from 'next/router';
import LanguageSelector from '../components/LanguageSelector';

function HomePage() {
  const { t, i18n } = useTranslation();
  const router = useRouter();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng).then(() => {
      router.push(router.asPath, router.asPath, { locale: lng });
    });
  };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('about_us')}</p>
      {t('contact_us')}
      
    </div>
  );
}

export default HomePage;

Here, we get the router instance using `useRouter`. In the `changeLanguage` function, we call `router.push` to update the URL. The `locale` option ensures that the new URL includes the selected language.

Handling Different Locales in Routing

Next.js provides several ways to handle different locales in your routes:

1. Automatic Locale Detection

By default, `next-i18next` automatically detects the user’s preferred language based on their browser settings (e.g., the `Accept-Language` header). This is usually the desired behavior, as it provides a seamless experience for users. If the user’s preferred language is one of the supported locales, the site will automatically render in that language. If the preferred language isn’t supported, it will fall back to the `defaultLocale` defined in `next-i18next.config.js`.

2. Locale Prefixes in URLs

You can configure your application to include the locale in the URL path. This is a common practice for SEO and user clarity. For example: `yourwebsite.com/en/about` and `yourwebsite.com/fr/a-propos`.

To enable locale prefixes, modify your `next-i18next.config.js`:

/** @type {import('next-i18next').UserConfig} */
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
    localeDetection: false, // Disable automatic locale detection
    domains: [
      {
        domain: 'yourwebsite.com',
        defaultLocale: 'en',
      },
      {
        domain: 'yourwebsite.fr',
        defaultLocale: 'fr',
      },
    ],
  },
}

Here’s what the configuration options do:

  • `localeDetection: false`: Disables automatic locale detection.
  • `domains`: Specifies the domain for each locale. Replace `’yourwebsite.com’` with your actual domain.

With this configuration, Next.js will use the domain to determine the locale.

3. Using the `next/link` component with locales

When using the `next/link` component to navigate between pages, make sure to include the `locale` prop to ensure the correct language is used in the URL.

import Link from 'next/link';
import { useRouter } from 'next/router';

function MyComponent() {
  const router = useRouter();
  const { locale } = router;

  return (
    
      <a>About Us</a>
    
  );
}

This ensures that the correct locale is applied to the generated URL.

SEO Considerations

When implementing i18n, it’s crucial to consider SEO best practices:

  • hreflang Tags: Use the `hreflang` attribute in your “ to tell search engines about the different language versions of your pages. This helps search engines understand the relationship between different language versions of your content and serve the appropriate version to users based on their language preferences.
  • Canonical URLs: Use canonical URLs to specify the preferred version of a page, especially if you have duplicate content across different languages. This tells search engines which version to index.
  • Unique URLs: Ensure each language version of a page has a unique URL. This is usually achieved by including the language code in the URL.
  • Sitemap: Create a sitemap that includes all language versions of your pages. This helps search engines discover and index your content.
  • Meta Descriptions and Titles: Translate your meta descriptions and titles to match the language of each page. This improves click-through rates.

Here’s an example of how to implement `hreflang` tags using the `next/head` component:

import Head from 'next/head';
import { useRouter } from 'next/router';

function MyComponent() {
  const router = useRouter();
  const { asPath, locale, locales, defaultLocale } = router;

  const baseUrl = 'https://yourwebsite.com'; // Replace with your website's URL

  const alternateLinks = locales.map((l) => {
    const href = l === defaultLocale ? baseUrl + asPath : `${baseUrl}/${l}${asPath}`;
    return {
      rel: 'alternate',
      hreflang: l,
      href,
    };
  });

  return (
    
      {alternateLinks.map((link) => (
        
      ))}
      {/* Add your canonical URL here */}
      
    
  );
}

In this example, we generate `hreflang` links for all supported locales. The `canonical` link points to the default locale version of the page.

Common Mistakes and How to Fix Them

Here are some common mistakes developers make when implementing i18n in Next.js, along with how to avoid them:

  • Incorrect Configuration: Ensure your `i18next` and Next.js configurations are set up correctly. Double-check your `defaultLocale`, `locales`, and translation file paths.
  • Missing Translations: Always provide translations for all the keys you use in your application. If a translation is missing, the `fallbackLng` will be used (if defined), or the key itself will be displayed, which can be confusing for users.
  • Hardcoding Text: Avoid hardcoding text directly in your components. Always use the `t` function to retrieve translations from your translation files.
  • Ignoring SEO: Remember to implement SEO best practices, including `hreflang` tags, canonical URLs, and unique URLs for each language version.
  • Forgetting to Update URLs: When changing the language, ensure your URLs are updated to reflect the selected language. Use the `next/router` for proper routing.
  • Not Testing Thoroughly: Test your application thoroughly in different languages to ensure all translations are displayed correctly and the user experience is smooth.

Key Takeaways

  • Choose the Right Library: `next-i18next` is a robust library for managing i18n in Next.js.
  • Structure Your Project: Organize your project with dedicated folders for i18n configurations and translation files.
  • Use the `useTranslation` Hook: This hook simplifies access to translations within your components.
  • Implement Language Switching: Provide a user-friendly way for users to switch between languages.
  • Consider SEO: Optimize your website for search engines by implementing `hreflang` tags and other SEO best practices.

FAQ

Q: How do I add a new language to my website?

A: First, add the language code (e.g., ‘es’ for Spanish) to the `locales` array in your `next-i18next.config.js` file. Then, create a new folder for the language in your `i18n/locales` directory (e.g., `i18n/locales/es`). Inside this folder, create a `translation.json` file (or your preferred name) and add the translations for the new language. Finally, make sure the new language is supported by your language selector component.

Q: How can I handle pluralization in my translations?

A: `i18next` supports pluralization. In your translation files, you can use keys with suffixes like `_plural` or `_0`, `_1`, `_2`, etc. Then, use the `t` function with the `count` option to select the correct plural form. Refer to the `i18next` documentation for details.

Q: How do I translate dynamic content?

A: You can use interpolation within your translation strings. Use placeholders like `{{variableName}}` in your translation files, and then pass the values in the `t` function’s second argument. For example: `t(‘greeting’, { name: ‘John’ })`. You can use this for any dynamic text, such as user names or dates.

Q: How do I deploy a multilingual Next.js website?

A: Deploying a multilingual Next.js website is no different than deploying a regular Next.js app. Make sure your hosting platform supports the features you are using, such as server-side rendering or static site generation. Consider using a Content Delivery Network (CDN) to serve your content globally, and ensure your deployment process correctly handles the different language versions of your website.

Q: How can I test my multilingual website?

A: Thorough testing is essential. Test your website in different browsers, devices, and locales. Check that the correct translations are displayed, the language selector works as expected, and the URLs are updated correctly. Use browser developer tools to inspect the `hreflang` tags and ensure they are correctly implemented. Consider using automated testing tools to test the functionality of your website across multiple languages.

Internationalizing your Next.js application empowers you to connect with a global audience, providing a more inclusive and user-friendly experience for everyone. By following the steps outlined in this tutorial, you can seamlessly integrate i18n into your projects, expanding your reach and making your content accessible to users worldwide. Remember to prioritize SEO best practices and testing to ensure your multilingual website performs at its best. Embrace the power of i18n, and create a truly global online presence.

More posts