Core library

Source URL: https://next-intl.dev/docs/environments/core-library

DocsEnvironmentsCore library

Core library

While next-intl is primarily intended to be used in Next.js apps, the core is agnostic and can be used independently—either in React apps or any other JavaScript environment.

React apps

next-intl internally uses a library called use-intl. This core library contains most features you’re familiar with from next-intl, but lacks the following Next.js-specific features:

1. Routing APIs
2. Awaitable APIs for Server Actions, Metadata and Route Handlers
3. Server Components integration along with i18n/request.ts

In case Server Components establish themselves in React apps outside of Next.js, the support for Server Components might be moved to the core library in the future.

In contrast, use-intl contains all APIs that are necessary for handling i18n in regular React apps:

• useTranslations for translating messages
• useFormatter for formatting numbers, dates & times and lists
• Configuration APIs (note however that NextIntlProvider is called IntlProvider in use-intl)

This allows you to use the same APIs that you know from next-intl in other environments:

1. React Apps (example)
2. React Native
3. Testing environments like Jest (example)
4. Storybook

Basic usage:

    import {IntlProvider, useTranslations} from 'use-intl';

    // You can get the messages from anywhere you like. You can also
    // fetch them from within a component and then render the provider
    // along with your app once you have the messages.
    const messages = {
      App: {
        hello: 'Hello {username}!'
      }
    };

    function Root() {
      return (
      );
    }

    function App({user}) {
      const t = useTranslations('App');
      return <h1>{t('hello', {username: user.name})}</h1>;
    }

Can I build shared components that work in both Next.js and plain React apps?

Yes, shared components that render in either environment are supported.

In this case, it can be beneficial to import from next-intl for the relevant components, to be able to benefit from the Server Components integration in case you render them in Next.js. In other environments, imports to next-intl will work as well, but will require IntlProvider to be present.

Non-React apps

Besides the React-specific APIs, use-intl also exports two low-level functions that can be used in any JavaScript environment:

1. createTranslator for translating messages
2. createFormatter for formatting numbers, dates & times and lists

These APIs receive all relevant configuration directly and don’t rely on global configuration.

You can use these APIs as follows:

    import {createTranslator, createFormatter} from 'use-intl/core';

    const messages = {
      basic: 'Hello {name}!',
      rich: 'Hello <b>{name}</b>!'
    };

    // This creates the same function that is returned by `useTranslations`.
    // Since there's no provider, you can pass all the properties you'd
    // usually pass to the provider directly here.
    const t = createTranslator({locale: 'en', messages});

    // Result: "Hello world!"
    t('basic', {name: 'world'});

    // To generate HTML markup, you can consider using the `markup`
    // function which in contrast to `t.rich` returns a markup string.
    t.markup('rich', {
      name: 'world',
      b: (chunks) => `<b>${chunks}</b>`
    });

    // Creates the same object that is returned by `useFormatter`.
    const format = createFormatter({locale: 'en'});

    // Result: "Oct 17, 2022"
    format.dateTime(new Date(2022, 9, 17), {dateStyle: 'medium'});