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:
- Routing APIs
- Awaitable APIs for Server Actions, Metadata and Route Handlers
- 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 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)
- 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'});