feat: next-intl@4 (#1412)

BREAKING CHANGE: See [announcement](https://next-intl.dev/blog/next-intl-4-0)

---------

Co-authored-by: amannn <[email protected]>
Co-authored-by: Thomas Wiringa <[email protected]>
Co-authored-by: felix-quotez <[email protected]>

Author: 3 people

.github/workflows/main.yml

@@ -7,7 +7,7 @@ on:
 jobs:
   build:
     name: Build, lint, and test
-    runs-on: ubuntu-latest
+    runs-on: macos-15
     env:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}

.github/workflows/prerelease.yml renamed to .github/workflows/prerelease-canary.yml

@@ -1,4 +1,4 @@
-name: prerelease
+name: prerelease (canary)
 
 on:
   push:
@@ -26,7 +26,7 @@ jobs:
       - run: |
           sed -i 's/"use-intl": "workspace:\^"/"use-intl": "workspace:"/' ./packages/next-intl/package.json && git commit -am "use fixed version"
       - run: pnpm lerna publish 0.0.0-canary-${GITHUB_SHA::7} --no-git-reset --dist-tag canary --no-push --yes
-        if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ')}}"
+        if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ') || startsWith(github.event.head_commit.message, 'feat!: ')}}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
           git config --global user.name "${{ github.actor }}"
           git config --global user.email "${{ github.actor }}@users.noreply.github.com"
       - run: pnpm run publish
-        if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ')}}"
+        if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ') || startsWith(github.event.head_commit.message, 'feat!: ')}}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

CONTRIBUTORS.md

@@ -86,7 +86,7 @@ Note that the exclamation mark syntax (`!`) for indicating breaking changes is c
 
 Other prefixes that are allowed and will _not_ create a release are the following:
 
-1. `docs`: Documentation-only changes
+1. `docs`: Documentation-only changes and updated examples
 2. `test`: Missing tests were added or existing ones corrected
 3. `ci`: Changes to CI configuration files and scripts
 4. `build`: Changes that affect the build system or external dependencies

docs/src/components/Footer.tsx

@@ -2,6 +2,7 @@ import {useRouter} from 'next/router';
 import config from '@/config';
 import FooterLink from './FooterLink';
 import FooterSeparator from './FooterSeparator';
+import FooterVersionSelector from './FooterVersionSelector';
 
 export default function Footer() {
   const router = useRouter();
@@ -19,6 +20,8 @@ export default function Footer() {
           <FooterLink href="/examples">Examples</FooterLink>
           <FooterSeparator />
           <FooterLink href="/blog">Blog</FooterLink>
+          <FooterSeparator />
+          <FooterVersionSelector />
         </div>
         <div>
           <FooterLink href={config.blueskyUrl} target="_blank">

docs/src/components/FooterVersionSelector.tsx

@@ -0,0 +1,19 @@
+import {ChangeEvent} from 'react';
+
+export default function FooterVersionSelector() {
+  function onChange(event: ChangeEvent<HTMLSelectElement>) {
+    const version = event.target.value;
+    window.location.href = `https://${version}.next-intl.dev`;
+  }
+
+  return (
+    <select
+      className="inline-flex appearance-none items-center bg-transparent py-3 text-xs text-slate-500 transition-colors hover:text-slate-900 dark:text-slate-400 dark:hover:text-white"
+      defaultValue="v4"
+      onChange={onChange}
+    >
+      <option value="v3">v3</option>
+      <option value="v4">v4</option>
+    </select>
+  );
+}

docs/src/pages/blog/_meta.tsx

@@ -3,7 +3,7 @@ export default {
     title: 'Overview'
   },
   'next-intl-4-0': {
-    title: 'next-intl 4.0 beta',
+    title: 'next-intl 4.0',
     display: 'hidden'
   },
   'next-intl-3-22': {

docs/src/pages/blog/index.mdx

@@ -6,8 +6,8 @@ import StayUpdated from '@/components/StayUpdated.mdx';
 <div className="flex flex-col gap-4 py-8">
   <BlogPostLink
     href="/blog/next-intl-4-0"
-    title="next-intl 4.0 beta"
-    date="Dec 23, 2024"
+    title="next-intl 4.0"
+    date="Mar 12, 2025"
     author="By Jan Amann"
   />
   <BlogPostLink

docs/src/pages/blog/next-intl-4-0.mdx

@@ -1,13 +1,13 @@
 ---
-title: next-intl 4.0 beta
+title: next-intl 4.0
 ---
 
 import PartnerContentLink from '@/components/PartnerContentLink';
 import StayUpdated from '@/components/StayUpdated.mdx';
 
-# next-intl 4.0 beta
+# next-intl 4.0
 
-<small>Dec 23, 2024 · by Jan Amann</small>
+<small>Mar 12, 2025 · by Jan Amann</small>
 
 After a year of feature development, this release focuses on streamlining the API surface while maintaining the core architecture of `next-intl`. With many improvements already released in [previous minor versions](/blog/next-intl-3-22), this update introduces several enhancements that will improve your development experience and make working with internationalization even more seamless.
 
@@ -44,7 +44,7 @@ declare module 'next-intl' {
 }
 ```
 
-See the updated [TypeScript augmentation](https://v4.next-intl.dev/docs/workflows/typescript) guide.
+See the updated [TypeScript augmentation](/docs/workflows/typescript) guide.
 
 ## Strictly-typed locale
 
@@ -65,7 +65,7 @@ declare module 'next-intl' {
 
 By doing so, APIs like `useLocale()` or `<Link />` that either return or receive a `locale` will now pick up your app-specific `Locale` type, improving type safety across your app.
 
-To simplify narrowing of `string`-based locales, a `hasLocale` function has been added. This can for example be used in [`i18n/request.ts`](https://v4.next-intl.dev/docs/getting-started/app-router/with-i18n-routing#i18n-request) to return a valid locale:
+To simplify narrowing of `string`-based locales, a `hasLocale` function has been added. This can for example be used in [`i18n/request.ts`](/docs/getting-started/app-router/with-i18n-routing#i18n-request) to return a valid locale:
 
 ```tsx
 import {getRequestConfig} from 'next-intl/server';
@@ -148,13 +148,13 @@ t('followers', {count: 30000});
 "{count, number} followers"
 ```
 
-Due to a current limitation in TypeScript, this feature is opt-in for now. Please refer to the [strict arguments](https://v4.next-intl.dev/docs/workflows/typescript#messages-arguments) docs to learn how to enable it.
+Due to a current limitation in TypeScript, this feature is opt-in for now. Please refer to the [strict arguments](/docs/workflows/typescript#messages-arguments) docs to learn how to enable it.
 
 ## GDPR compliance [#gdpr-compliance]
 
 In order to comply with the current GDPR regulations, the following changes have been made and are relevant to you if you're using the `next-intl` middleware for i18n routing:
 
-1. The locale cookie now defaults to a session cookie that expires when a browser is closed.
+1. The locale cookie now defaults to a session cookie that expires when the browser is closed.
 2. The locale cookie is now only set when a user switches to a locale that doesn't match the `accept-language` header.
 
 If you want to increase the cookie expiration, e.g. because you're informing users about the usage of cookies or if GDPR doesn't apply to your app, you can use the `maxAge` attribute to do so:
@@ -174,11 +174,11 @@ export const routing = defineRouting({
 });
 ```
 
-Since the cookie is now only available after a locale switch, make sure to not rely on it always being present. E.g. if you need access to the user's locale in a [Route Handler](https://v4.next-intl.dev/docs/environments/actions-metadata-route-handlers#route-handlers), a reliable option is to provide the locale as a search param (e.g. `/api/posts/12?locale=en`).
+Since the cookie is now only available after a locale switch, make sure to not rely on it always being present. E.g. if you need access to the user's locale in a [Route Handler](/docs/environments/actions-metadata-route-handlers#route-handlers), a reliable option is to provide the locale as a search param (e.g. `/api/posts/12?locale=en`).
 
-As part of this change, disabling a cookie now requires you to set [`localeCookie: false`](https://v4.next-intl.dev/docs/routing#locale-cookie) in your routing configuration. Previously, `localeDetection: false` ambiguously also disabled the cookie from being set, but since a separate `localeCookie` option was introduced recently, this should now be used instead.
+As part of this change, disabling a cookie now requires you to set [`localeCookie: false`](/docs/routing#locale-cookie) in your routing configuration. Previously, `localeDetection: false` ambiguously also disabled the cookie from being set, but since a separate `localeCookie` option was introduced recently, this should now be used instead.
 
-Learn more in the [locale cookie](https://v4.next-intl.dev/docs/routing#locale-cookie) docs.
+Learn more in the [locale cookie](/docs/routing#locale-cookie) docs.
 
 ## Modernized build output
 
@@ -266,7 +266,7 @@ This will create the following structure:
 - `example.no`: `no-NO`
 - `example.no/en`: `en-NO`
 
-Learn more in the updated docs for [`domains`](https://v4.next-intl.dev/docs/routing#domains).
+Learn more in the updated docs for [`domains`](/docs/routing#domains).
 
 ## Preparation for upcoming Next.js features [#nextjs-future]
 
@@ -300,11 +300,9 @@ For a smooth upgrade, please initially upgrade to the latest v3.x version and ch
 Afterwards, you can upgrade by running:
 
 ```
-npm install next-intl@v4-beta
+npm install next-intl@4
 ```
 
-The beta docs are available here: [v4.next-intl.dev](https://v4.next-intl.dev)
-
 I'd love to hear about your experiences with `[email protected]`! Join the conversation in the [discussions](https://github.com/amannn/next-intl/discussions/1631).
 
 ## Thank you!
@@ -315,6 +313,8 @@ A special thank you goes to <PartnerContentLink href="https://crowdin.com/">Crow
 
 —Jan
 
+(this post has been updated from an initial announcement for the 3.0 release candidate)
+
 PS: Have you heard that [learn.next-intl.dev](https://learn.next-intl.dev) is coming?
 
 <StayUpdated />

docs/src/pages/docs/environments/actions-metadata-route-handlers.mdx

@@ -173,8 +173,9 @@ Note that by default, `next-intl` returns [the `link` response header](/docs/rou
 
 Next.js supports providing alternate URLs per language via the [`alternates` entry](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap#generate-a-localized-sitemap). You can construct a list of entries for each pathname and locale as follows:
 
-```tsx filename="app/sitemap.ts" {4-5,8-9}
+```tsx filename="app/sitemap.ts" {5-6,9-10}
 import {MetadataRoute} from 'next';
+import {Locale} from 'next-intl';
 import {routing, getPathname} from '@/i18n/routing';
 
 // Adapt this as necessary
@@ -198,7 +199,7 @@ function getEntries(href: Href) {
   }));
 }
 
-function getUrl(href: Href, locale: (typeof routing.locales)[number]) {
+function getUrl(href: Href, locale: Locale) {
   const pathname = getPathname({locale, href});
   return host + pathname;
 }
@@ -230,12 +231,17 @@ You can use `next-intl` in [Route Handlers](https://nextjs.org/docs/app/building
 
 ```tsx filename="app/api/hello/route.tsx"
 import {NextResponse} from 'next/server';
+import {hasLocale} from 'next-intl';
 import {getTranslations} from 'next-intl/server';
+import {routing} from '@/i18n/routing';
 
 export async function GET(request) {
   // Example: Receive the `locale` via a search param
   const {searchParams} = new URL(request.url);
   const locale = searchParams.get('locale');
+  if (!hasLocale(routing.locales, locale)) {
+    return NextResponse.json({error: 'Invalid locale'}, {status: 400});
+  }
 
   const t = await getTranslations({locale, namespace: 'Hello'});
   return NextResponse.json({title: t('title')});

docs/src/pages/docs/environments/error-files.mdx

@@ -77,16 +77,16 @@ export default function RootLayout({children}) {
 }
 ```
 
-For the 404 page to render, we need to call the `notFound` function in the root layout when we detect an incoming `locale` param that isn't a valid locale.
+For the 404 page to render, we need to call the `notFound` function in the root layout when we detect an incoming `locale` param that isn't valid.
 
 ```tsx filename="app/[locale]/layout.tsx"
+import {hasLocale} from 'next-intl';
 import {notFound} from 'next/navigation';
+import {routing} from '@/i18n/routing';
 
-export default async function LocaleLayout({children, params}) {
+export default function LocaleLayout({children, params}) {
   const {locale} = await params;
-
-  // Ensure that the incoming `locale` is valid
-  if (!routing.locales.includes(locale as any)) {
+  if (!hasLocale(routing.locales, locale)) {
     notFound();
   }
 

docs/src/pages/docs/environments/server-client-components.mdx

@@ -69,14 +69,17 @@ These functions are available:
 
 Components that aren't declared with the `async` keyword and don't use interactive features like `useState`, are referred to as [shared components](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md#sharing-code-between-server-and-client). These can render either as a Server or Client Component, depending on where they are imported from.
 
-In Next.js, Server Components are the default, and therefore shared components will typically execute as Server Components.
+In Next.js, Server Components are the default, and therefore shared components will typically execute as Server Components:
 
 ```tsx filename="UserDetails.tsx"
 import {useTranslations} from 'next-intl';
 
 export default function UserDetails({user}) {
   const t = useTranslations('UserProfile');
 
+  // This component will execute as a Server Component by default.
+  // However, if it is imported from a Client Component, it will
+  // execute as a Client Component.
   return (
     <section>
       <h2>{t('title')}</h2>
@@ -112,11 +115,13 @@ Regarding performance, async functions and hooks can be used interchangeably. Th
 
 ## Using internationalization in Client Components
 
-Depending on your situation, you may need to handle internationalization in Client Components. While providing all messages to the client side is typically the easiest way to [get started](/docs/getting-started/app-router#layout) and a reasonable approach for many apps, you can be more selective about which messages are passed to the client side if you're interested in optimizing the performance of your app.
+Depending on your situation, you may need to handle internationalization in Client Components. Providing all messages to the client side is the easiest way to get started, therefore `next-intl` automatically does this when you render [`NextIntlClientProvider`](/docs/usage/configuration#nextintlclientprovider). This is a reasonable approach for many apps.
+
+However, you can be more selective about which messages are passed to the client side if you're interested in optimizing the performance of your app.
 
 There are several options for using translations from `next-intl` in Client Components, listed here in order of enabling the best performance:
 
-### Option 1: Passing translations to Client Components
+### Option 1: Passing translated labels to Client Components
 
 The preferred approach is to pass the processed labels as props or `children` from a Server Component.
 
@@ -275,8 +280,6 @@ In particular, page and search params are often a great option because they offe
 
 ### Option 3: Providing individual messages
 
-To reduce bundle size, `next-intl` doesn't automatically provide [messages](/docs/usage/configuration#messages) or [formats](/docs/usage/configuration#formats) to Client Components.
-
 If you need to incorporate dynamic state into components that can not be moved to the server side, you can wrap these components with `NextIntlClientProvider` and provide the relevant messages.
 
 ```tsx filename="Counter.tsx"
@@ -312,22 +315,16 @@ An automatic, compiler-driven approach is being evaluated in [`next-intl#1`](htt
 
 ### Option 4: Providing all messages
 
-If you're building a highly dynamic app where most components use React's interactive features, you may prefer to make all messages available to Client Components.
+If you're building a highly dynamic app where most components use React's interactive features, you may prefer to make all messages available to Client Components—this is the default behavior of `next-intl`.
 
 ```tsx filename="layout.tsx" /NextIntlClientProvider/
 import {NextIntlClientProvider} from 'next-intl';
-import {getMessages} from 'next-intl/server';
 
 export default async function RootLayout(/* ... */) {
-  // Receive messages provided in `i18n/request.ts`
-  const messages = await getMessages();
-
   return (
     <html lang={locale}>
       <body>
-        <NextIntlClientProvider messages={messages}>
-          {children}
-        </NextIntlClientProvider>
+        <NextIntlClientProvider>{children}</NextIntlClientProvider>
       </body>
     </html>
   );
@@ -366,7 +363,6 @@ The component accepts the following props that are not serializable:
 
 1. [`onError`](/docs/usage/configuration#error-handling)
 2. [`getMessageFallback`](/docs/usage/configuration#error-handling)
-3. Rich text elements for [`defaultTranslationValues`](/docs/usage/configuration#default-translation-values)
 
 To configure these, you can wrap `NextIntlClientProvider` with another component that is marked with `'use client'` and defines the relevant props.