Comprehensive Guide to Next Intl: Translating and Internationalizing Next.js Websites

Do you want your Next.js website to be available in different languages and attract a global audience? Are you tired of the complexities of managing translations and localization? Next Intl is your solution!

In this article, we will take a comprehensive look at the Next Intl library and teach you step-by-step how to use it for internationalization (i18n) and localization (l10n) of Next.js websites. Join us to see how you can easily create a powerful multilingual website.

What is Next Intl and why should we use it?

Next Intl is a powerful and flexible library for internationalizing Next.js applications. By providing a simple and efficient API, this library facilitates the translation and localization process and helps you make your website available in different languages.

Benefits of using Next Intl:

Simplicity: A simple and practical API that makes the translation process easy.
Flexibility: Supports various translation formats and different content management methods.
High Performance: Optimized to provide the best user experience on multilingual websites.
Next.js Support: Full integration with Next.js and taking advantage of the features of this framework.
Active Community: A large and active community that helps you solve problems and learn.

In short, Next Intl is an essential tool for any developer who wants to turn their Next.js website into a global product.

Getting Started with Next Intl: Installation and Setup

To get started with Next Intl, you must first install it in your Next.js project. To do this, use the following command in the terminal:

npm install next-intl

After installation, you need to configure Next Intl in your next.config.js. This tells Next.js to use Next Intl for managing translations. Also, create a middleware.ts file and connect it to next-intl.

// next.config.js
const withNextIntl = require('next-intl/plugin')('./i18n.ts');

module.exports = withNextIntl({
  // Other Next.js configuration ...
});

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

export default createMiddleware({
  // A list of all locales that are supported
  locales: ['en', 'fa'],
  // Used when no locale matches
  defaultLocale: 'fa'
});

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

In this example, we have defined two languages, English (en) and Persian (fa), as supported languages. We have also set the default language to Persian. i18n.ts includes the language settings of the application.

Structure of Translation Files: Organization and Management

One of the most important aspects of internationalization is organizing and managing translation files. Next Intl uses a simple and logical structure for this purpose. Usually, translation files are in the locales folder.

Structure of Translation Files:

locales/
  en.json
  fa.json
  ...

Each JSON file contains translations related to a specific language. For example, the fa.json file contains Persian translations and the en.json file contains English translations.

Example Translation File (fa.json):

{
  "greeting": "سلام دنیا!",
  "welcomeMessage": "به وب‌سایت ما خوش آمدید!",
  "productName": "محصول",
  "addToCart": "افزودن به سبد خرید"
}

In this file, each key represents an identifier for a specific text, and the value is the equivalent translation of that text into Persian.

Using Translations in Components: Different Methods

Next Intl offers various methods for using translations in Next.js components. One of the simplest methods is to use the useTranslations hook.

Using the useTranslations Hook:

import { useTranslations } from 'next-intl';

function MyComponent() {
  const t = useTranslations('ComponentName');

  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('description')}</p>
    </div>
  );
}

export default MyComponent;

In this example, we use the useTranslations hook to retrieve translations related to the MyComponent component. Then, using the t function, we can access the desired translations. ComponentName is a namespace and you can categorize messages.

Another example with FormattedMessage:

import { FormattedMessage } from 'next-intl';

function MyComponent() {
  return (
    <div>
      <h1>
        <FormattedMessage id="greeting" defaultMessage="Hello, world!" />
      </h1>
    </div>
  );
}

export default MyComponent;

In this example, we use the <FormattedMessage> component to display the translation. This component receives an id and a defaultMessage. If a translation is not found for the desired id, the defaultMessage is displayed.

Language Management: Changing Language and Detecting User Language

Next Intl allows you to easily change the website language and detect the user's language. To change the language, you can use the <Link> component provided by Next.js.

Changing Language Using <Link>:

import Link from 'next/link';

function LanguageSwitcher() {
  return (
    <div>
      <Link href="/" locale="en">
        <a>English</a>
      </Link>
      <Link href="/" locale="fa">
        <a>فارسی</a>
      </Link>
    </div>
  );
}

export default LanguageSwitcher;

In this example, we have created two links to change the language to English and Persian. By clicking on each link, the website language changes to the desired language. This library automatically reads the language from the Accept-Language header and displays the site accordingly.

Detecting User Language:

Next Intl automatically detects the user's language from the Accept-Language header of the HTTP request and displays the website in the appropriate language. You can also manually detect the user's language using the API provided by Next Intl.

Advanced Tips: Customization and Optimization

Next Intl offers advanced features for customizing and optimizing the internationalization process. Some of these features include:

Using Different Translation Formats: Next Intl supports various translation formats such as JSON, YAML, and PO.
Customizing the Translation Loading Process: You can customize the translation loading process according to your needs.
Performance Optimization: Next Intl provides features for optimizing the performance of multilingual websites, such as using cache and compressing translation files.

Practical Example: Building a Multilingual Website with Next Intl

To better understand how to use Next Intl, let's look at a practical example. Suppose we want to create a simple website with two pages (homepage and about us page) that is available in both English and Persian.

Steps to Build a Multilingual Website:

Install and Setup Next Intl: As explained earlier, install and configure Next Intl in your Next.js project.
Create Translation Files: Create the en.json and fa.json translation files and place the translations for each page in these files.
Use Translations in Components: Use translations in your components using the useTranslations hook or the <FormattedMessage> component.
Create Language Change Links: Create links to change the language using the <Link> component.
Test and Review: Test your website and make sure that the translations are displayed correctly and the language change links work correctly.

By following these steps, you can easily create a multilingual website with Next Intl.

Summary

Next Intl is a powerful and efficient library for internationalizing Next.js websites. Using this library, you can easily make your website available in different languages and attract a global audience. I hope this guide has helped you learn and use Next Intl. Now you can build your multilingual website and make it available to your global audience.

Frequently Asked Questions (FAQ)

1. What is Next Intl and what is it used for?

Next Intl is a library for internationalization (i18n) of Next.js applications. This library helps you translate your website into different languages and attract a global audience. Globalize your website with Next Intl.

2. How can I install Next Intl in my Next.js project?

To install Next Intl, use the command npm install next-intl or yarn add next-intl in the terminal.

3. How can I detect the user's language with Next Intl?

Next Intl automatically detects the user's language from the Accept-Language header of the HTTP request. You can also manually detect the user's language using the API provided by Next Intl.

4. Does Next Intl support different translation formats?

Yes, Next Intl supports various translation formats such as JSON, YAML, and PO.

5. How can I optimize the performance of my multilingual website with Next Intl?

Next Intl provides features for optimizing the performance of multilingual websites, such as using cache and compressing translation files.