next-intl

What is next-intl?

The next-intl package is designed to provide internationalization (i18n) support for Next.js applications. It allows developers to easily manage translations, handle locale routing, and format dates, numbers, and other content according to locale-specific rules.

What are next-intl's main functionalities?

Translation Management

This feature allows you to manage translations for different components. The `useTranslations` hook is used to fetch the translations for a specific namespace, and you can then use the translation keys to display localized text.

import { useTranslations } from 'next-intl';

export default function MyComponent() {
  const t = useTranslations('MyComponent');
  return <p>{t('hello')}</p>;
}

Locale Routing

This feature allows you to handle locale-specific routing in your Next.js application. By using the `useRouter` hook, you can programmatically change the locale and update the URL accordingly.

import { useRouter } from 'next/router';

export default function LocaleSwitcher() {
  const router = useRouter();
  const changeLocale = (locale) => {
    router.push(router.pathname, router.asPath, { locale });
  };
  return (
    <div>
      <button onClick={() => changeLocale('en')}>English</button>
      <button onClick={() => changeLocale('fr')}>French</button>
    </div>
  );
}

Date and Number Formatting

This feature allows you to format dates, numbers, and other content according to locale-specific rules. The `useIntl` hook provides methods like `formatDate` to format dates in a localized manner.

import { useIntl } from 'next-intl';

export default function DateFormatter() {
  const intl = useIntl();
  const formattedDate = intl.formatDate(new Date(), { year: 'numeric', month: 'long', day: 'numeric' });
  return <p>{formattedDate}</p>;
}

Other packages similar to next-intl

react-intl

react-intl is a popular library for internationalizing React applications. It provides similar functionalities to next-intl, such as translation management and date/number formatting. However, it does not offer built-in support for Next.js-specific features like locale routing.

i18next

i18next is a powerful internationalization framework that can be used with various JavaScript libraries, including React. It offers extensive features for managing translations, handling pluralization, and more. While it is more versatile, it requires additional setup to integrate with Next.js compared to next-intl.

next-translate

next-translate is another Next.js-specific internationalization library. It provides similar functionalities to next-intl, such as translation management and locale routing. However, next-translate uses a different approach for loading translations and may have different performance characteristics.

README

next-intl

Minimal, but complete solution for managing translations in Next.js apps.

The problem

Next.js has built-in support for internationalized routing, but doesn't have an opinion about how you should handle your translations.

This solution

This is my attempt at providing a minimal, but complete solution that fills in the missing pieces.

function LatestFollower({user}) {
  const t = useTranslations('LatestFollower');

  return (
    <>
      <Text>{t('latestFollower', {username: user.name})}</Text>
      <IconButton aria-label={t('followBack')} icon={<FollowIcon />} />
    </>
  );
}

// en.json
{
  "LatestFollower": {
    "latestFollower": "{username} started following you",
    "followBack": "Follow back"
  }
}

Features

• Based on battle-tested building blocks from Format.JS (used by react-intl), this library is a thin wrapper around high-quality APIs for i18n.
• I18n is really essential for usability, therefore this library doesn't compromise on flexibility and never leaves you behind when you need to fine tune a translation. Messages use the proven ICU syntax.
• The bundle size comes in at 32.2kb (9.2kb gzipped) which is the tradeoff that's necessary for the flexibility of the library.
• A hooks-only API ensures that you can use the same API for children as well as for attributes which expect strings.
• Integration with Next.js ensures only the least amount of configuration is necessary.

Installation

• Install next-intl in your project
• Add the provider in _app.js

import {NextIntlProvider} from 'next-intl';
import NextApp from 'next/app';

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

App.getInitialProps = async function getInitialProps(context) {
  const {locale} = context.router;

  // You can get the messages from anywhere you like, but the recommended
  // pattern is to put them in JSON files separated by language and read 
  // the desired one based on the `locale` received from Next.js. You
  // can also separate your messages further (e.g. by page) and read
  // them based on the current route.
  const messages = locale ? require(`messages/${locale}.json`) : undefined

  return {...(await NextApp.getInitialProps(context)), messages};
};

• Based on the features you need and the browsers you support, you might have to provide polyfills.
• Use translations in your components!

Usage

// en.json

{
  // The recommended approach is to group messages by components.
  "Component": {
    "static": "Hello",

    // See https://formatjs.io/docs/core-concepts/icu-syntax/#simple-argument
    "interpolation": "Hello {name}",

    // See https://formatjs.io/docs/core-concepts/icu-syntax/#number-type
    "number": "{price, number, ::currency/EUR}",
    
    // See https://formatjs.io/docs/intl-messageformat#datetime-skeleton
    "date": "{now, date, medium}",
    
    // See https://formatjs.io/docs/core-concepts/icu-syntax/#plural-format
    "plural": "You have {numMessages, plural, =0 {no messages} =1 {one message} other {# messages}}.",
    
    // See https://formatjs.io/docs/core-concepts/icu-syntax/#select-format
    "select": "{gender, select, male {He} female {She} other {They}} is online.",
    
    // See https://formatjs.io/docs/core-concepts/icu-syntax/#selectordinal-format
    "selectordinal": "It's my cat's {year, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} birthday!",

    // See https://formatjs.io/docs/core-concepts/icu-syntax/#rich-text-formatting
    // and https://formatjs.io/docs/intl-messageformat/#rich-text-support
    "richText": "This is <important><very>very</very> important</important>",

    // Messages can be used in attributes
    "attributeUrl": "https://example.com",

    // Use nesting to provide more structure
    "nested": {
      "label": "Nested"
    }
  },

  // You don't have to group messages by components. Use whatever suits your use case.
  "generic": {
    "cancel": "Cancel"
  },

  // You can also put your components behind namespaces.
  "fancyComponents": {
    "FancyComponent": {
      "hello": "Hello"
    }
  }
}

function Component() {
  const t = useTranslations('Component');
  return (
    <p>{t('static')}</p>
    <p>{t('interpolation', {name: 'Jane'})}</p>
    <p>{t('number', {price: 31918.231})}</p>
    <p>{t('date', {date: new Date('2020-11-20T10:36:01.516Z')})}</p>
    <p>{t('plural', {date: new Date('2020-11-20T10:36:01.516Z')})}</p>
    <p>{t('selectordinal', {year: 1})}</p>
    <p>
      {t('richText', {
        important: (children: ReactNode) => <b>{children}</b>,
        very: (children: ReactNode) => <i>{children}</i>,
      })}
    </p>
    // TypeScript note: You have to cast the attribute to a string, since it 
    // can potentially return a `ReactNode`: `String(t('attributeUrl'))`
    <a href={t('attributeUrl')}>Link</a>
    <p>{t('nested.label')}</p>
  );
}

function AllTranslations() {
  // You can get all translations if you omit the namespace path.
  const t = useTranslations();
}

function FancyComponent() {
  // Or you can get messages from a nested namespace. The way the library works
  // is that there's a static path of the messages that is resolved in the hook
  // and should supply all necessary translations for the component. The remaining
  // hierarchy can be resolved by passing the respective path to the `t` function.
  const t = useTranslations('fancyComponents.FancyComponent');
}

Tradeoffs

• All relevant translations for the components need to be supplied to the provider – there's no concept of lazy loading translations. If your app has a significant number of messages, the page-based approach of Next.js allows you to only provide the minimum of necessary messages based on the route. If you split your components by features, it might make sense to split your translation files the same way. Ideally a build-time plugin would take care of creating message bundles based on the components used on a page (this would have to include potentially lazy loaded components as well though).
• There are smaller libraries for internationalisation, but they typically cover less features than Format.JS. However if your performance budget doesn't allow for the size of this library, you might be better off with an alternative.

TODO

• Cache format result?
• Pass currency to number? (if currency is sensitive to locale, use the messages)
• Relative time
• Check other features of react-intl