next-intl 3.0
Nov 14, 2023 · by Jan AmannMore than a year ago, on Oct 25, 2022, Next.js 13 was announced (opens in a new tab) with beta support for the App Router and Server Components. Ever since then, next-intl
began an exploration on what it means to provide an ideal experience for implementing i18n with the newly added capabilities.
Today, after more than 370 commits and the involvement of over 60 community members (opens in a new tab), I'm absolutely thrilled to announce next-intl 3.0, which is now App Router-first.
If you're still happy with the Pages Router, rest assured that next-intl
is dedicated to support this paradigm for as long as Next.js does. For those who have already migrated to the App Router, this means that you can take full advantage of the new capabilities with next-intl
.
New features
- Support for React Server Components: The APIs
useTranslations
,useFormatter
,useLocale
,useNow
anduseTimeZone
can now be used in Server Components (docs). - New async APIs: To handle i18n in async components, the Metadata API and Route Handlers, the APIs
getTranslations
,getFormatter
,getNow
, andgetTimeZone
have been added (docs). - Middleware for internationalized routing: While Next.js has built-in support for this with the Pages Router, the App Router doesn't include a built-in solution anymore.
next-intl
now provides a drop-in solution that has you covered (docs). - Internationalized navigation APIs: Similar to the middleware, this provides a drop-in solution that adds internationalization support for Next.js' navigation APIs:
Link
,useRouter
,usePathname
andredirect
. These APIs allow you to handle locale prefixes behind the scenes and also provide support for localizing pathnames (e.g./en/about
vs./de/ueber-uns
, see the docs).
The latter two have already been added in minor versions, but 3.0 cleans up the API and includes many improvements and bug fixes.
Breaking changes
Users of pre-releases: If you've already tried out pre-release versions, first of all, thank you so much! Second: Some APIs saw iterations over the pre-release period, please carefully review the breaking changes below, even if you're already using some of the new APIs. Also note the change from getTranslator
to getTranslations
(opens in a new tab) to provide better ergonomics for working with async Server Components.
Updated setup
next-intl
now requires two additional setup steps when you're using the App Router:
- The
i18n.ts
module provides configuration for Server Components next-intl/plugin
needs to be added to link youri18n.ts
module tonext-intl
New navigation APIs for the App Router
With v2.14 (opens in a new tab), the navigation APIs useRouter
, usePathname
and Link
were added to next-intl
that enabled you to use the APIs you're used to from Next.js while automatically considering a locale
behind the scenes.
With 3.0, we're cleaning up these APIs by moving them to a shared namespace as well as introducing type-safety for the locale
prop that can be passed to these APIs.
- import Link from 'next-intl/link';
- import {useRouter, usePathname} from 'next-intl/client';
- import {redirect} from 'next-intl/server';
+ import {createSharedPathnamesNavigation} from 'next-intl/navigation';
+
+ const locales = ['en', 'de'] as const;
+ const {Link, useRouter, usePathname, redirect} = createSharedPathnamesNavigation({locales});
Typically, you'll want to call this factory function in a central place in your app where you can easily import from (see the navigation docs).
These changes bring the existing APIs in line with the new createLocalizedPathnamesNavigation
API that allows you to localize pathnames:
import {createLocalizedPathnamesNavigation, Pathnames} from 'next-intl/navigation';
export const locales = ['en', 'de'] as const;
// The `pathnames` object holds pairs of internal
// and external paths, separated by locale.
export const pathnames = {
// If all locales use the same pathname, a
// single external path can be provided.
'/': '/',
'/blog': '/blog',
// If locales use different paths, you can
// specify each external path per locale.
'/about': {
en: '/about',
de: '/ueber-uns'
}
} satisfies Pathnames<typeof locales>;
export const {Link, redirect, usePathname, useRouter} =
createLocalizedPathnamesNavigation({locales, pathnames});
By using a similar API, you can upgrade from shared pathnames to localized pathnames by replacing the factory function.
Switching the middleware default of localePrefix
to always
Previously, the localePrefix
of the middleware defaulted to as-needed
, meaning that a locale prefix was only added for non-default locales.
This default has now been changed to always
since this has two advantages:
- We can recommend a safer default
matcher
that needs no extra treatment for pathnames with dots (e.g./users/jane.doe
) - It avoids an edge case of
Link
where we include a prefix for the default locale on the server side but patch this on the client side by removing the prefix (certain SEO tools might report a hint that a link points to a redirect in this case).
If you want to stay on the as-needed
strategy, you can configure this option in the middleware.
Static rendering of Server Components
With the newly introduced Server Components support comes a temporary workaround for static rendering.
If you call APIs from next-intl
in Server Components, the page will by default opt into dynamic rendering (opens in a new tab). This is a limitation that we aim to remove in the future, but as a stopgap solution, we've added the unstable_setRequestLocale
API so that you can keep your pages fully static.
Note that if you're using next-intl
exclusively in Client Components, this doesn't apply to your app and static rendering will continue to work as it did before.
Changes to NextIntlClientProvider
First, the import for this component has changed:
- import {NextIntlClientProvider} from 'next-intl/client';
+ import {NextIntlClientProvider} from 'next-intl';
Depending on if you're using NextIntlClientProvider
with or without the App Router, there's been another change to consider that was implemented in order to avoid hydration mismatches across the server and client.
Using NextIntlClientProvider
without the App Router
If you're using NextIntlClientProvider
without the App Router (e.g. with the Pages Router), you need to define the locale
prop now explicitly (e.g. via useRouter().locale
). Furthermore, a warning has been added if a timeZone
hasn't been defined.
Using NextIntlClientProvider
with the App Router
If you're using NextIntlClientProvider
with the App Router, there has been a slight change to the semantics. If you're rendering NextIntlClientProvider
within a Server Component, the component will pass defaults for locale
, now
and timeZone
to the client side.
If you're already providing these options, then you're set.
If you're not, be aware that this will by default opt the corresponding page into dynamic rendering. If your app relies on static rendering, you can avoid this by passing all of the mentioned options:
<NextIntlClientProvider
messages={messages}
// By providing these props explicitly,
// the provider can render statically.
timeZone="Europe/Vienna"
now={new Date()}
locale={locale}
>
...
</NextIntlClientProvider>
Alternatively, you can explicitly enable static rendering—see the previous section.
Other notable changes
next-intl
now usesexports
inpackage.json
(opens in a new tab) to clearly define which modules are exported. This should not affect you, unless you've previously imported undocumented internals.NextIntlProvider
has been removed in favor ofNextIntlClientProvider
- The middleware now needs to be imported from
next-intl/middleware
instead ofnext-intl/server
(deprecated since v2.14). next@^13.4
is now required for the RSC APIs. Next.js 12 is still supported for the Pages Router integration.useMessages
now has a non-nullable return type for easier consumption and will throw if no messages are configured.createTranslator(…).rich
now returns aReactNode
. Previously, this was somewhat confusing, sincet.rich
accepted and returned either React elements or strings depending on if you retrieve the fuction viauseTranslations
orcreateTranslator
. Now, an explicitt.markup
function has been added to generate markup strings like'<b>Hello</b>'
outside of React components.useIntl
has been replaced withuseFormatter
(deprecated since v2.11).createIntl
has been replaced withcreateFormatter
(deprecated since v2.11).useLocale
now requiresnext@>=13.3.0
. If you're on an older version of Next.js and you're using the Pages Router, please useuseRouter().locale
instead.
Upgrade now
npm install next-intl@latest
Thank you
This release was truly a team effort and couldn't be nearly where it is today without the involvement of the community.
Thank you so much for:
- All the encouraging words along the way
- Testing out prereleases
- Providing feedback
- Contributing code
- Questioning ideas
- Helping each other
I had the pleasure to get in touch with so many of you along the way and I'm incredibly grateful for the willingness to help and support each other in our community.
A special thank you goes to Crowdin (opens in a new tab), being the primary sponsor for next-intl
and enabling me to regularly dedicate time for this project.
—Jan
(this post has been updated from an initial announcement for the 3.0 release candidate)