feat!: next-intl@4

.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 → .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/prerelease-v4.yml

@@ -0,0 +1,33 @@
+name: prerelease (v4)
+
+on:
+  push:
+    branches:
+      - v4
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          registry-url: 'https://registry.npmjs.org'
+          node-version: 20.x
+          cache: 'pnpm'
+      - run: pnpm install
+      - run: |
+          git config --global user.name "${{ github.actor }}"
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+      - 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 4.0.0-beta-${GITHUB_SHA::7} --no-git-reset --dist-tag v4-beta --no-push --yes
+        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 }}
+          NPM_CONFIG_PROVENANCE: true

.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 }}

docs/src/components/StayUpdated.mdx

@@ -2,6 +2,5 @@
 
 **Let's keep in touch:**
 
-- [GitHub releases](https://github.com/amannn/next-intl/releases)
 - [Bluesky (Jan Amann)](https://bsky.app/profile/amann.work)
 - [X (Jan Amann)](https://x.com/jamannnnnn)

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

@@ -154,8 +154,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) as of version 14.2. You can use your default locale for the main URL and provide alternate URLs based on all locales that your app supports. Keep in mind that also the default locale should be included in the `alternates` object.
 
-```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
@@ -179,7 +180,7 @@ function getEntry(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;
 }
@@ -206,12 +207,16 @@ 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';
 
 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(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,14 +77,15 @@ 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 function LocaleLayout({children, params: {locale}}) {
-  // 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>
@@ -275,7 +278,7 @@ 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.
+To reduce bundle size, `next-intl` doesn't automatically provide [messages](/docs/usage/configuration#messages) 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.
 
@@ -366,7 +369,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.
 

docs/src/pages/docs/getting-started/app-router/with-i18n-routing.mdx

@@ -147,16 +147,15 @@ When using features from `next-intl` in Server Components, the relevant configur
 
 ```tsx filename="src/i18n/request.ts"
 import {getRequestConfig} from 'next-intl/server';
+import {hasLocale} from 'next-intl';
 import {routing} from './routing';
 
 export default getRequestConfig(async ({requestLocale}) => {
-  // This typically corresponds to the `[locale]` segment
-  let locale = await requestLocale;
-
-  // Ensure that a valid locale is used
-  if (!locale || !routing.locales.includes(locale as any)) {
-    locale = routing.defaultLocale;
-  }
+  // Typically corresponds to the `[locale]` segment
+  const requested = await requestLocale;
+  const locale = hasLocale(routing.locales, requested)
+    ? requested
+    : routing.defaultLocale;
 
   return {
     locale,
@@ -186,7 +185,7 @@ const withNextIntl = createNextIntlPlugin(
 The `locale` that was matched by the middleware is available via the `locale` param and can be used to configure the document language. Additionally, we can use this place to pass configuration from `i18n/request.ts` to Client Components via `NextIntlClientProvider`.
 
 ```tsx filename="app/[locale]/layout.tsx"
-import {NextIntlClientProvider} from 'next-intl';
+import {NextIntlClientProvider, Locale, hasLocale} from 'next-intl';
 import {getMessages} from 'next-intl/server';
 import {notFound} from 'next/navigation';
 import {routing} from '@/i18n/routing';
@@ -196,10 +195,9 @@ export default async function LocaleLayout({
   params: {locale}
 }: {
   children: React.ReactNode;
-  params: {locale: string};
+  params: {locale: Locale};
 }) {
-  // Ensure that the incoming `locale` is valid
-  if (!routing.locales.includes(locale as any)) {
+  if (!hasLocale(routing.locales, locale)) {
     notFound();
   }
 
@@ -297,12 +295,12 @@ export function generateStaticParams() {
 
 ```tsx filename="app/[locale]/layout.tsx"
 import {setRequestLocale} from 'next-intl/server';
+import {hasLocale} from 'next-intl';
 import {notFound} from 'next/navigation';
 import {routing} from '@/i18n/routing';
 
 export default async function LocaleLayout({children, params: {locale}}) {
-  // Ensure that the incoming `locale` is valid
-  if (!routing.locales.includes(locale as any)) {
+  if (!hasLocale(routing.locales, locale)) {
     notFound();
   }
 

docs/src/pages/docs/getting-started/pages-router.mdx

@@ -109,9 +109,3 @@ export async function getStaticProps() {
 </ul>
 
 </Callout>
-
-## Support for legacy Next.js versions
-
-Next.js version 10, 11 and 12 are still supported. Note however that instead of installing `next-intl`, you'll have to import functionality like `useTranslations` from [`use-intl`](/docs/environments/core-library#react-apps).
-
-See the [legacy example](https://github.com/amannn/next-intl/tree/main/examples/example-pages-router-legacy).

docs/src/pages/docs/routing.mdx

@@ -110,8 +110,8 @@ In this case, requests for all locales will be rewritten to have the locale only
 **Note that:**
 
 1. If you use this strategy, you should adapt your matcher to detect [unprefixed pathnames](/docs/routing/middleware#matcher-no-prefix).
-2. If you don't use domain-based routing, the cookie is now the source of truth for determining the locale. Make sure that your hosting solution reliably returns the `set-cookie` header from the middleware (e.g. Vercel and Cloudflare are known to potentially [strip this header](https://developers.cloudflare.com/cache/concepts/cache-behavior/#interaction-of-set-cookie-response-header-with-cache) for cacheable requests).
-3. [Alternate links](#alternate-links) are disabled in this mode since URLs might not be unique per locale. Due to this, consider including these yourself, or set up a [sitemap](/docs/environments/actions-metadata-route-handlers#sitemap) that links localized pages via `alternates`.
+2. [Alternate links](#alternate-links) are disabled in this mode since URLs might not be unique per locale. Due to this, consider including these yourself, or set up a [sitemap](/docs/environments/actions-metadata-route-handlers#sitemap) that links localized pages via `alternates`.
+3. You can consider increasing the [`maxAge`](#locale-cookie) attribute of the locale cookie to a longer duration to remember the user's preference across sessions.
 
 #### Custom prefixes [#locale-prefix-custom]
 
@@ -297,11 +297,12 @@ In case you're using a system like a CMS to configure localized pathnames, you'l
 
 ```tsx filename="page.tsx"
 import {notFound} from 'next';
+import {Locale} from 'next-intl';
 import {fetchContent} from './cms';
 
 type Props = {
   params: {
-    locale: string;
+    locale: Locale;
     slug: Array<string>;
   };
 };
@@ -472,11 +473,10 @@ In this case, only the locale prefix and a potentially [matching domain](#domain
 
 ### Locale cookie [#locale-cookie]
 
-By default, the middleware will set a cookie called `NEXT_LOCALE` that contains the most recently detected locale. This is used to [remember the user's locale](/docs/routing/middleware#locale-detection) preference for future requests.
+If a user changes the locale to a value that doesn't match the `accept-language` header, `next-intl` will set a session cookie called `NEXT_LOCALE` that contains the most recently detected locale. This is used to [remember the user's locale](/docs/routing/middleware#locale-detection) preference for subsequent requests.
 
 By default, the cookie will be configured with the following attributes:
 
-1. [**`maxAge`**](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#max-agenumber): This value is set to 1 year so that the preference of the user is kept as long as possible.
 2. [**`sameSite`**](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value): This value is set to `lax` so that the cookie can be set when coming from an external site.
 3. [**`path`**](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value): This value is not set by default, but will use the value of your [`basePath`](#base-path) if configured.
 
@@ -492,8 +492,8 @@ export const routing = defineRouting({
   localeCookie: {
     // Custom cookie name
     name: 'USER_LOCALE',
-    // Expire in one day
-    maxAge: 60 * 60 * 24
+    // Expire in one year
+    maxAge: 60 * 60 * 24 * 365
   }
 });
 ```
@@ -510,7 +510,20 @@ export const routing = defineRouting({
 });
 ```
 
-Note that the cookie is only set when the user switches the locale and is not updated on every request.
+<Details id="locale-cookie-gdpr">
+<summary>Which `maxAge` value should I consider for GDPR compliance?</summary>
+
+The [Article 29 Working Party opinion 04/2012](https://ec.europa.eu/justice/article-29/documentation/opinion-recommendation/files/2012/wp194_en.pdf) provides a guideline for the expiration of cookies that are used to remember the user's language in section 3.6 "UI customization cookies". In this policy, a language preference cookie set as a result of an explicit user action, such as using a language switcher, is allowed to remain active for "a few additional hours" after a browser session has ended.
+
+To be compliant out of the box, `next-intl` does not set the `max-age` value of the cookie, making it a session cookie that expires when a browser is closed.
+
+Note that this can be beneficial in comparison to an expiration of a few hours since the cookie is guaranteed to remain active while the browser session lasts. On mobile devices, where browsers are infrequently closed but rather suspended to the background, the cookie can remain active even for an extended period.
+
+The Working Party also states that if additional information about the use of cookies is provided in a prominent location (e.g. a "uses cookies" notice next to the language switcher), the cookie can be configured to remember the user's preference for "a longer duration". If you're providing such a notice, you can consider increasing `maxAge` accordingly.
+
+Please note that legal requirements may vary by region, so it's advisable to verify them independently. While we strive to keep this information as up-to-date as possible, we cannot guarantee its accuracy.
+
+</Details>
 
 ### Alternate links [#alternate-links]
 

docs/src/pages/docs/routing/middleware.mdx

@@ -30,7 +30,7 @@ export const config = {
 
 ## Locale detection [#locale-detection]
 
-The locale is negotiated based on your [`localePrefix`](/docs/routing#locale-prefix) and [`domains`](/docs/routing#domains) setting. Once a locale is detected, it will be remembered for future requests by being stored in the `NEXT_LOCALE` cookie.
+The locale is negotiated based on your routing configuration, taking into account your settings for [`localePrefix`](/docs/routing#locale-prefix), [`domains`](/docs/routing#domains), [`localeDetection`](/docs/routing#locale-detection), and [`localeCookie`](/docs/routing#locale-cookie).
 
 ### Prefix-based routing (default) [#location-detection-prefix]
 
@@ -48,10 +48,11 @@ To change the locale, users can visit a prefixed route. This will take precedenc
 **Example workflow:**
 
 1. A user requests `/` and based on the `accept-language` header, the `en` locale is matched.
-2. The `en` locale is saved in a cookie and the user is redirected to `/en`.
+2. The user is redirected to `/en`.
 3. The app renders `<Link locale="de" href="/">Switch to German</Link>` to allow the user to change the locale to `de`.
 4. When the user clicks on the link, a request to `/de` is initiated.
-5. The middleware will update the cookie value to `de`.
+5. The middleware will add a cookie to remember the preference for the `de` locale.
+6. The user later requests `/` again and the middleware will redirect to `/de` based on the cookie.
 
 <Details id="accept-language-matching">
 <summary>Which algorithm is used to match the accept-language header against the available locales?</summary>

docs/src/pages/docs/routing/navigation.mdx

@@ -374,14 +374,3 @@ const pathname = getPathname({
   }
 });
 ```
-
-## Legacy APIs
-
-`next-intl@3.0.0` brought the first release of the navigation APIs with these functions:
-
-- `createSharedPathnamesNavigation`
-- `createLocalizedPathnamesNavigation`
-
-As part of `next-intl@3.22.0`, these functions have been replaced by a single `createNavigation` function, which unifies the API for both use cases and also fixes a few quirks in the previous APIs. Going forward, `createNavigation` is recommended and the previous functions are marked as deprecated.
-
-While `createNavigation` is mostly API-compatible, there are some minor differences that should be noted. Please refer to the [3.22 announcement post](/blog/next-intl-3-22#create-navigation) for full details.