FAQ

What trade-offs does this library make?

  1. The bundle size comes in at 39.8kB (12kb gzipped) which is the tradeoff that's necessary for supporting all the mentioned internationalization features. There are smaller libraries for internationalization, but they typically cover less features. If you don't need all features of next-intl, you can reduce the bundle size with tree shaking. However if your performance budget doesn't allow for the size of this library, you might be better off with an alternative.
  2. Currently 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 to provide bundles per feature set. A built-in mechanism for lazy loading is being evaluated in #2.

How is this library different from using react-intl?

  1. This library is built around the concept of namespaces and that components consume a single namespace (however this is not required).
  2. This library offers a hooks-only API for message consumption. The reason for this is that the same API can be used for attributes as well as children.
  3. This library currently doesn't support AST-based extraction like react-intl.
  4. This library is a bit smaller in size (next-intl vs react-intl on BundlePhobia).

How can I parse dates or manipulate them?

This library is only concerned with formatting dates. A great library to parse and manipulate dates is date-fns.

Note that parsing dates with new Date(dateString) and Date.parse(dateString) is discouraged due to browser differences and inconsistencies (see the MDN docs on the Date constructor).

Can this be used without Next.js?

Yes, see use-intl.

Can this be used with Remix?

Yes, see the Remix example.

Can next-intl be used with testing libraries like Jest and Storybook?

Yes. These environments pose the challenge that components render in isolation and therefore relevant providers might be missing. To fix this, you should wrap the component with NextIntlProvider.

Please see the Jest example to explore a working setup. For Storybook, you have to add a global decorator that configures the provider.