FAQ

What trade-offs does this library make?

If you bundle next-intl for the client side (which you don't have to), the bundle size comes in at ~14kB gzipped which is the tradeoff that's necessary for supporting all the included i18n 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. Furthermore if native Intl.MessageFormat (opens in a new tab) lands in JavaScript in the future, we might be able to reduce the bundle size significantly.

Generally, it's recommended to handle internationalization in Server Components to avoid bundling next-intl for the client side in the first place.

How is this library different from using react-intl?

This library offers tight integration with Next.js, e.g. through the routing integration and Server Components support.
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.
This library is built around the concept of namespaces and that components consume a single namespace—however this is not required.
This library currently doesn't support AST-based extraction like react-intl. Note that building ASTs for messages upfront can help with runtime performance, but in exchange your bundle size might grow.
This library is a bit smaller in size.
This library offers type safety for message keys.

Can `next-intl` be used with 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 NextIntlClientProvider.

Please see the Jest example (opens in a new tab) to explore a working setup. For Storybook, you have to add a global decorator (opens in a new tab) that configures the provider.