Global configuration

Configuration properties that you commonly use across your Next.js app for internationalization can be set globally on the provider.

Time zone

If possible, you should configure an explicit time zone as this affects the rendering of dates and times. By default, the available time zone of the runtime will be used: In Node.js this is the time zone that is configured for the server and in the browser this is the local time zone of the user. As the time zone of the server and the one from the user will likely be different, this can be problematic when your app is both rendered on the server as well as on the client side.

To avoid such markup mismatches, you can globally define a time zone like this:

<NextIntlProvider timeZone="Europe/Vienna">...<NextIntlProvider>

This can either be static in your app, or alternatively read from the user profile if you store such a setting. The available time zone names can be looked up in the tz database (opens in a new tab).

Global now value

To avoid mismatches between the server and client environment, it is recommended to configure a static global now value on the provider:

<NextIntlProvider
  // This value can be generated in data fetching functions
  // of individual pages or `App.getInitialProps`.
  now={now}
  ...
>
  <App />
</NextIntlProvider>

This value will be used as the default for the relativeTime function as well as for the initial render of useNow.

For consistent results in end-to-end tests, it can be helpful to mock this value to a constant value, e.g. based on an environment parameter.

Global formats

To achieve consistent date, time and number formatting across your app, you can define a set of global formats and pass them to the provider.

<NextIntlProvider
  ...
  formats={{
    dateTime: {
      short: {
        day: 'numeric',
        month: 'short',
        year: 'numeric'
      }
    },
    number: {
      precise: {
        maximumFractionDigits: 5
      }
    }
  }}
>
  <App />
</NextIntlProvider>

import {useFormatter} from 'next-intl';
 
function Component() {
  const format = useFormatter();
 
  format.dateTime(new Date('2020-11-20T10:36:01.516Z'), 'short');
  format.number(47.414329182, 'precise');
}

Global formats can be referenced in messages too.

{
  "ordered": "You've ordered this product on {orderDate, date, short}",
  "latitude": "Latitude: {latitude, number, precise}"
}

import {useTranslations} from 'next-intl';
 
function Component() {
  const t = useTranslations();
 
  t('ordered', {orderDate: new Date('2020-11-20T10:36:01.516Z')});
  t('latitude', {latitude: 47.414329182});
}

Default translation values

To achieve consistent usage of translation values and reduce redundancy, you can define a set of global default values and pass them to the provider. This configuration also can be used to apply consistent styling to commonly used rich text elements.

<NextIntlProvider
  ...
  defaultTranslationValues={{
    important: (chunks) => <b>{chunks}</b>,
    value: 123
  }}
>
  <App />
</NextIntlProvider>

The defaults will be overridden by locally provided values.

Retrieve provider config

As a convenience, two hooks exist that allow to read configuration that was passed to the provider.

import {useLocale, useTimeZone} from 'next-intl';
 
function Component() {
  // Returns either an explicitly configured locale from the
  // provider or if internationalized routing is set up, it
  // returns the configured locale from Next.js.
  const locale = useLocale();
 
  // Note that this will be `undefined` if no explicit
  // `timeZone` was configured on the provider.
  const timeZone = useTimeZone();
}