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:
- Routing APIs
- Awaitable APIs for Server Actions, Metadata and Route Handlers
- 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:
useTranslations
for translating messagesuseFormatter
for formatting numbers, dates & times and lists- Configuration APIs (note however that
NextIntlProvider
is calledIntlProvider
inuse-intl
)
This allows you to use the same APIs that you know from next-intl
in other environments:
- React Apps (example)
- React Native (example)
- Remix (example)
- Testing environments like Jest (example (opens in a new tab))
- 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 (
<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:
createTranslator
for translating messagescreateFormatter
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'});