Rendering i18n messages

Optionally, you can structure your messages as nested objects.

{
  "auth": {
    "SignUp": {
      "title": "Sign up",
      "form": {
        "placeholder": "Please enter your name",
        "submit": "Submit"
      }
    }
  }
}

import {useTranslations} from 'next-intl';
 
function SignUp() {
  // Provide the lowest common denominator that contains
  // all messages this component needs to consume.
  const t = useTranslations('auth.SignUp');
 
  return (
    <>
      <h1>{t('title')}</h1>
      <form>
        <input
          // The remaining hierarchy can be resolved by
          // using `.` to access nested messages.
          placeholder={t('form.placeholder')}
        />
        <button type="submit">{t('form.submit')}</button>
      </form>
    </>
  );
}

As your app grows, you'll want to reuse messages among your components. If you use component names as namespaces to structure your messages, you'll automatically benefit from reusable messages by reusing your components.

Examples:

• You're displaying products in your app and often need to resolve a category identifier to a human readable label (e.g. new → "Just in"). To ensure consistency, you can add a ProductCategory component that turns the category into a styled badge.
• You commonly need a dialog that displays a "confirm" and "cancel" button. In this case, consider adding a ConfirmDialog component to reuse the messages along with the functionality.

There might be cases where you want to use the same message in different components, but there's no reasonable opportunity for sharing the message via a component. This might be symptom that these components should use separate messages, even if they happen to be the same for the time being. By using separate labels, you gain the flexibility to use more specific labels (e.g. "not now" instead of "cancel").

For edge cases where the reuse of messages among different components is hard to achieve with shared components, you can either use messages from different namespaces via useTranslations(), or you can consider adding a hook that shares the translation behavior:

export default function useLocaleLabel() {
  const t = useLocaleLabel('useLocaleLabel');
 
  function getLocaleLabel(locale: 'en' | 'de') {
    return t('label', {locale});
  }
 
  return getLocaleLabel;
}

{
  "useLocaleLabel": {
    "label": "{locale, select, en {English} de {German} other {Unknown}}"
  }
}

next-intl is heavily based on the useTranslations API which is intended to consume translations from within React components. This may seem like a limitation, but this is intentional and aims to encourage the use of proven patterns that avoid potential issues—especially if they are easy to overlook.

If you're interested to dive deeper into this topic, there's a blog post that discusses the background of this design decision: How (not) to use translations outside of React components.

There's one exception however: Using next-intl with the Next.js Metadata API and Route Handlers.

Depending on the language, different forms of cardinal pluralization are supported.

For example, English has two forms: One for the singular (e.g. "1 follower") and one for everything else (e.g. "0 followers" and "2 followers"). In contrast, Chinese only has one form, while Arabic has six.

next-intl uses Intl.PluralRules (opens in a new tab) to detect the correct tag that should be used for a given number.

These tags are supported:

• zero
• one
• two
• few
• many
• other

The exact range that few and many applies to varies depending on the locale (see the language plural rules table in the Unicode CLDR (opens in a new tab)).

To match a specific number, next-intl additionally supports the special =value syntax (e.g. =3) that always takes precedence.

Depending on the language, different forms of ordinal pluralization are supported.

For example, English has four forms: "th", "st", "nd" and "rd" (e.g. 1st, 2nd, 3rd, 4th … 21st, 22nd, 23rd, 24th, etc.). In contrast, both Chinese and Arabic use only one form for ordinal numbers.

next-intl uses Intl.PluralRules (opens in a new tab) to detect the correct tag that should be used for a given number.

These tags are supported:

• zero
• one
• two
• few
• many
• other

The exact range that few and many applies to varies depending on the locale (see the language plural rules table in the Unicode CLDR (opens in a new tab)).

To match a specific number, next-intl additionally supports the special =value syntax (e.g. =3) that always takes precedence.

If you want to use the same tag across your app, you can configure it via default translation values.

Messages can use tags without any chunks as children, but syntax-wise, a closing tag is required by the ICU parser:

{
  "message": "Hello,<br></br>how are you?"
}

t.rich('message', {
  br: () => <br />
});

Attributes can only be set on the call site, not within messages:

{
  "message": "Go to <profile>my profile</profile>"
}

t.rich('message', {
  profile: (chunks) => <Link href="/profile">{chunks}</Link>
});

For the use case of localizing pathnames, consider using createLocalizedPathnamesNavigation.

In case you have attribute values that are required to be configured as part of your messages, you can retrieve them from a separate message and pass them to another one as an attribute:

{
  "message": "See this <partner>partner website</partner>.",
  "partnerHref": "https://partner.example.com"
}

t.rich('message', {
  partner: (chunks) => <a href={t('partnerHref')}>{chunks}</a>
});

To dynamically iterate over all keys of a namespace, you can use the useMessages hook to retrieve all messages of a given namespace and extract the keys from there:

import {useTranslations, useMessages} from 'next-intl';
 
function CompanyStats() {
  const t = useTranslations('CompanyStats');
 
  const messages = useMessages();
  const keys = Object.keys(messages.CompanyStats);
 
  return (
    <ul>
      {keys.map((key) => (
        <li key={key}>
          <h2>{t(`${key}.title`)}</h2>
          <p>{t(`${key}.value`)}</p>
        </li>
      ))}
    </ul>
  );
}