Skip to content
Docs
Environments
Core 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 is based on a library called use-intl (opens in a new tab) that is developed in parallel.

This core library contains most features of 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.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:

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

  1. React Apps (example)
  2. React Native (example)
  3. Remix (example)
  4. Testing environments like Jest (example (opens in a new tab))
  5. Storybook (by using a global decorator (opens in a new tab))

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 (
    <IntlProvider messages={messages} locale="en">
      <App user={{name: 'Jane'}} />
    </IntlProvider>
  );
}
 
function App({user}) {
  const t = useTranslations('App');
  return <h1>{t('hello', {username: user.name})}</h1>;
}

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';
 
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'});
Markdown (MDX)Runtime requirements

Docs

 · 

Examples

 · 

Blog