Merge remote-tracking branch 'origin/main' into chore/next-15

Author: amannn

Diff for: .github/ISSUE_TEMPLATE/02_feature_request.yml

@@ -6,10 +6,18 @@ labels:
 body:
   - type: markdown
     attributes:
-      value: Thanks for taking the time to file a feature request! Please fill out this form completely.
+      value: Thanks for taking the time to improve next-intl!
   - type: markdown
     attributes:
-      value: Please keep in mind that if something doesn't work as expected, you might want to [create a bug report](https://github.com/amannn/next-intl/issues/new/choose) instead. Bug reports disguised as feature requests will be closed.
+      value: |
+        Please keep in mind:
+
+        - If you're looking for specific support with your project, you can consider [asking for community support](https://github.com/amannn/next-intl/issues/new/choose) instead.
+        - If something doesn't work as expected, you might want to [create a bug report](https://github.com/amannn/next-intl/issues/new/choose) instead.
+        - Please double check the [docs](https://next-intl.dev) to see if your feature request is already supported.
+        - Please also check the [existing issues](https://github.com/amannn/next-intl/issues) to see if your feature request was already discussed.
+
+        If you have a feature request that has not been discussed yet, please fill out this form completely.
   - type: textarea
     attributes:
       label: Is your feature request related to a problem? Please describe.

Diff for: .github/ISSUE_TEMPLATE/config.yml

@@ -3,9 +3,15 @@ contact_links:
   - name: View documentation
     url: https://next-intl.dev
     about: Check out the official docs for answers to common questions
-  - name: Get community support
+  - name: Get community support on the Next.js Discord
+    url: https://discord.com/invite/nextjs
+    about: Join the Next.js community on Discord to get real-time help and connect with other developers
+  - name: Get community support on Stack Overflow
     url: https://stackoverflow.com/questions/ask
-    about: Ask questions and discuss with other community members
+    about: Post your technical questions on Stack Overflow where experienced developers can help
+  - name: Get community support on GitHub Discussions
+    url: https://github.com/amannn/next-intl/discussions
+    about: Start a discussion to share ideas and ask questions
   - name: Get maintainer support
     url: https://github.com/sponsors/amannn?frequency=one-time
     about: Book a consulting session to get help with your specific project

Diff for: CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## 3.26.5 (2025-02-21)
+
+### Bug Fixes
+
+* Handle `query` in `<Link />` correctly when using `localePrefix: 'as-needed'` with `domains` ([#1732](https://github.com/amannn/next-intl/issues/1732)) ([ec8776e](https://github.com/amannn/next-intl/commit/ec8776e8f0344f78fea4f71284c48312484a7059)), closes [#1731](https://github.com/amannn/next-intl/issues/1731) – by @amannn
+
+## 3.26.4 (2025-02-18)
+
+### Bug Fixes
+
+* Add workaround for OpenTelemetry/Zone.js ([#1719](https://github.com/amannn/next-intl/issues/1719)) ([1cac9a6](https://github.com/amannn/next-intl/commit/1cac9a65d2aefe20ff7fcf734e70f1fe85cac19d)), closes [#1711](https://github.com/amannn/next-intl/issues/1711) – by @amannn
+
 ## 3.26.3 (2024-12-20)
 
 ### Bug Fixes

Diff for: docs/src/components/HeroCode.tsx

@@ -164,7 +164,7 @@ const files = [
           <span data-token="text">:</span>
           <span data-token="text"> </span>
           <span data-token="string">
-            "{'{'}firstname{'}'}'s profile"
+            "{'{'}firstName{'}'}'s profile"
           </span>
           <span data-token="text">,</span>
         </span>

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

@@ -18,7 +18,9 @@ Here's what's new in `next-intl@4.0`:
 3. [**Strictly-typed ICU arguments**](#strictly-typed-icu-arguments)
 4. [**GDPR compliance**](#gdpr-compliance)
 5. [**Modernized build output**](#modernized-build-output)
-6. [**Preparation for upcoming Next.js features**](#nextjs-future)
+6. [**Improved inheritance in `NextIntlClientProvider`**](#nextintlclientprovider-inheritance)
+7. [**Stricter config for `domains`**](#domains-config)
+8. [**Preparation for upcoming Next.js features**](#nextjs-future)
 
 Please also have a look at the [other breaking changes](#other-breaking-changes) listed below before you upgrade.
 
@@ -188,6 +190,82 @@ The build output of `next-intl` has been modernized and now leverages the follow
 
 With these changes, the bundle size of `next-intl` has been reduced by ~7% ([all details](https://github.com/amannn/next-intl/pull/1470)).
 
+## Improved inheritance of `NextIntlClientProvider` [#nextintlclientprovider-inheritance]
+
+Previously, [`NextIntlClientProvider`](/docs/usage/configuration#nextintlclientprovider) would conservatively inherit only a subset from `i18n/request.ts`.
+
+To improve the getting started experience, the provider now also inherits:
+
+- `messages` ([PR #1682](https://github.com/amannn/next-intl/pull/1682))
+- `formats` ([PR #1191](https://github.com/amannn/next-intl/pull/1191))
+
+Due to this, you can now remove these props from `NextIntlClientProvider` if you've previously passed them manually:
+
+```diff
+<NextIntlClientProvider
+-  messages={messages}
+-  formats={formats}
+>
+  {/* ... */}
+</NextIntlClientProvider>
+```
+
+With this, `NextIntlClientProvider` now inherits all of your configuration, with the minor exception of [error handling functions](/docs/usage/configuration#error-handling). Since functions are not serializable, they cannot be passed across the server/client boundary. However, [an alternative](https://github.com/amannn/next-intl/issues/1285) for this is also on the horizon.
+
+To make it easier to work with error handling functions on the client side, `NextIntlClientProvider` can now also be used in a nested fashion and will inherit the configuration from a parent provider ([PR #1413](https://github.com/amannn/next-intl/pull/1413)).
+
+## Stricter config for `domains` [#domains-config]
+
+So far, when using [`domains`](/docs/routing#domains) in combination with [`localePrefix: 'as-needed'`](/docs/routing#locale-prefix-as-needed), `next-intl` had to make some [tradeoffs](https://next-intl-docs-6wwcmwb9a-next-intl.vercel.app/docs/routing#domains-localeprefix-asneeded) to avoid reading the current host of the incoming request in components.
+
+Now, by introducing two new constraints, `next-intl` can avoid these tradeoffs altogether:
+
+1. A locale can now only be used for a single domain
+2. Each domain now must specify its `locales`
+
+The result is a simplified, more intuitive model that works as expected for this popular use case.
+
+If you previously used locales across multiple domains, you now have to be more specific—typically by introducing a regional variant for a base language. You can additionally customize the prefixes if desired.
+
+**Example:**
+
+```tsx
+import {defineRouting} from 'next-intl/routing';
+
+export const routing = defineRouting({
+  locales: ['sv-SE', 'en-SE', 'no-NO', 'en-NO'],
+  defaultLocale: 'en-SE',
+  localePrefix: {
+    mode: 'as-needed',
+    prefixes: {
+      'en-SE': '/en',
+      'en-NO': '/en'
+    }
+  },
+  domains: [
+    {
+      domain: 'example.se',
+      defaultLocale: 'sv-SE',
+      locales: ['sv-SE', 'en-SE']
+    },
+    {
+      domain: 'example.no',
+      defaultLocale: 'no-NO',
+      locales: ['no-NO', 'en-NO']
+    }
+  ]
+});
+```
+
+This will create the following structure:
+
+- `example.se`: `sv-SE`
+- `example.se/en`: `en-SE`
+- `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).
+
 ## Preparation for upcoming Next.js features [#nextjs-future]
 
 To ensure that the sails of `next-intl` are set for a steady course in the upcoming future, I've investigated the implications of upcoming Next.js features like [`ppr`](https://nextjs.org/docs/app/api-reference/next-config-js/ppr), [`dynamicIO`](https://nextjs.org/docs/canary/app/api-reference/config/next-config-js/dynamicIO) and [`rootParams`](https://github.com/vercel/next.js/pull/72837) for `next-intl`.
@@ -196,7 +274,7 @@ This led to three minor changes:
 
 1. If you don't already have a `NextIntlClientProvider` in your app that wraps all Client Components that use `next-intl`, you now have to add one (see [PR #1541](https://github.com/amannn/next-intl/pull/1541) for details).
 2. If you're using `format.relativeTime` in Client Components, you may need to provide the `now` argument explicitly now (see [PR #1536](https://github.com/amannn/next-intl/pull/1536) for details).
-3. If you're using i18n routing, make sure you've updated to [`await requestLocale`](https://next-intl.dev/blog/next-intl-3-22#await-request-locale) that was introduced in `next-intl@3.22`. The previously deprecated `locale` argument will serve an edge case in the future once `rootParams` is a thing (see [PR #1625](https://github.com/amannn/next-intl/pull/1625/) for details).
+3. If you're using i18n routing, make sure you've updated to [`await requestLocale`](/blog/next-intl-3-22#await-request-locale) that was introduced in `next-intl@3.22`. The previously deprecated `locale` argument will serve an edge case in the future once `rootParams` is a thing (see [PR #1625](https://github.com/amannn/next-intl/pull/1625/) for details).
 
 While the mentioned Next.js features are still under development and may change, these changes seem reasonable to me in any case—and ideally will be all that's necessary to adapt for `next-intl` to get the most out of these upcoming capabilities.
 
@@ -205,13 +283,12 @@ I'm particularly excited about the announcement of `rootParams`, as it seems lik
 ## Other breaking changes
 
 1. Return type-safe messages from `useMessages` and `getMessages` (see [PR #1489](https://github.com/amannn/next-intl/pull/1489))
-2. Inherit context in case nested `NextIntlClientProvider` instances are present (see [PR #1413](https://github.com/amannn/next-intl/pull/1413))
-3. Automatically inherit formats when `NextIntlClientProvider` is rendered from a Server Component (see [PR #1191](https://github.com/amannn/next-intl/pull/1191))
-4. Require locale to be returned from `getRequestConfig` (see [PR #1486](https://github.com/amannn/next-intl/pull/1486))
-5. Disallow passing `null`, `undefined` or `boolean` as an ICU argument (see [PR #1561](https://github.com/amannn/next-intl/pull/1561))
-6. Bump minimum required TypeScript version to 5 for projects using TypeScript (see [PR #1481](https://github.com/amannn/next-intl/pull/1481))
-7. Remove deprecated APIs (see [PR #1479](https://github.com/amannn/next-intl/pull/1479))
-8. Remove deprecated APIs pt. 2 (see [PR #1482](https://github.com/amannn/next-intl/pull/1482))
+2. Require locale to be returned from `getRequestConfig` (see [PR #1486](https://github.com/amannn/next-intl/pull/1486))
+3. Disallow passing `null`, `undefined` or `boolean` as an ICU argument (see [PR #1561](https://github.com/amannn/next-intl/pull/1561))
+4. Bump minimum required TypeScript version to 5 for projects using TypeScript (see [PR #1481](https://github.com/amannn/next-intl/pull/1481))
+5. Return `x-default` alternate link also for sub pages when using `localePrefix: 'always'` and update middleware matcher suggestion in docs (see [PR #1720](https://github.com/amannn/next-intl/pull/1720))
+6. Remove deprecated APIs (see [PR #1479](https://github.com/amannn/next-intl/pull/1479))
+7. Remove deprecated APIs pt. 2 (see [PR #1482](https://github.com/amannn/next-intl/pull/1482))
 
 ## Upgrade now
 

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

@@ -81,22 +81,18 @@ async function loginAction(data: FormData) {
   const t = await getTranslations('LoginForm');
   const values = Object.fromEntries(data);
 
-  const result = await loginFormSchema
-    .refine(async (credentials) => loginUser(credentials), {
-      message: t('invalidCredentials')
-    })
-    .safeParseAsync(values, {
-      errorMap(issue, ctx) {
-        const path = issue.path.join('.');
-
-        const message = {
-          email: t('invalidEmail')
-          password: t('invalidPassword')
-        }[path];
-
-        return {message: message || ctx.defaultError};
-      }
-    });
+  const result = loginFormSchema.safeParse(values, {
+    errorMap(issue, ctx) {
+      const path = issue.path.join('.');
+
+      const message = {
+        email: t('invalidEmail')
+        password: t('invalidPassword')
+      }[path];
+
+      return {message: message || ctx.defaultError};
+    }
+  });
 
   // ...
 }
@@ -175,7 +171,7 @@ If you're using a sitemap to inform search engines about all pages of your site,
 
 Note that by default, `next-intl` returns [the `link` response header](/docs/routing#alternate-links) to instruct search engines that a page is available in multiple languages. While this sufficiently links localized pages for search engines, you may choose to provide this information in a sitemap in case you have more specific requirements.
 
-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.
+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}
 import {MetadataRoute} from 'next';
@@ -186,20 +182,20 @@ const host = 'https://acme.com';
 
 export default function sitemap(): MetadataRoute.Sitemap {
   // Adapt this as necessary
-  return [getEntry('/'), getEntry('/users')];
+  return [...getEntries('/'), ...getEntries('/users')];
 }
 
 type Href = Parameters<typeof getPathname>[0]['href'];
 
-function getEntry(href: Href) {
-  return {
-    url: getUrl(href, routing.defaultLocale),
+function getEntries(href: Href) {
+  return routing.locales.map((locale) => ({
+    url: getUrl(href, locale),
     alternates: {
       languages: Object.fromEntries(
-        routing.locales.map((locale) => [locale, getUrl(href, locale)])
+        routing.locales.map((cur) => [cur, getUrl(href, cur)])
       )
     }
-  };
+  }));
 }
 
 function getUrl(href: Href, locale: (typeof routing.locales)[number]) {
@@ -212,15 +208,20 @@ Depending on if you're using the [`pathnames`](/docs/routing#pathnames) setting,
 
 ```tsx
 // 1. A final string (when not using `pathnames`)
-getEntry('/users/1');
+getEntries('/users/1');
 
 // 2. An object (when using `pathnames`)
-getEntry({
+getEntries({
   pathname: '/users/[id]',
   params: {id: '1'}
 });
 ```
 
+**Keep in mind**:
+
+- Each pathname should have a separate entry for every locale that your app supports.
+- Also the locale of a given pathname should be included in the `alternates` object.
+
 ([working implementation](https://github.com/amannn/next-intl/blob/main/examples/example-app-router/src/app/sitemap.ts))
 
 ### Route Handlers

Diff for: docs/src/pages/docs/usage/configuration.mdx

@@ -190,7 +190,7 @@ export default async function RootLayout({children}) {
           messages={messages}
         >
           {children}
-        </NextIntlClientProvider>
+        </IntlProvider>
       </body>
     </html>
   );

Diff for: examples/example-app-router/src/app/sitemap.ts

@@ -4,20 +4,20 @@ import {routing, Locale} from '@/i18n/routing';
 import {getPathname} from '@/i18n/navigation';
 
 export default function sitemap(): MetadataRoute.Sitemap {
-  return [getEntry('/'), getEntry('/pathnames')];
+  return [...getEntries('/'), ...getEntries('/pathnames')];
 }
 
 type Href = Parameters<typeof getPathname>[0]['href'];
 
-function getEntry(href: Href) {
-  return {
-    url: getUrl(href, routing.defaultLocale),
+function getEntries(href: Href) {
+  return routing.locales.map((locale) => ({
+    url: getUrl(href, locale),
     alternates: {
       languages: Object.fromEntries(
-        routing.locales.map((locale) => [locale, getUrl(href, locale)])
+        routing.locales.map((cur) => [cur, getUrl(href, cur)])
       )
     }
-  };
+  }));
 }
 
 function getUrl(href: Href, locale: Locale) {

Diff for: examples/example-app-router/tests/main.spec.ts

@@ -111,10 +111,20 @@ it('serves a sitemap.xml', async ({page}) => {
 <xhtml:link rel="alternate" hreflang="de" href="http://localhost:3000/de" />
 </url>
 <url>
+<loc>http://localhost:3000/de</loc>
+<xhtml:link rel="alternate" hreflang="en" href="http://localhost:3000/en" />
+<xhtml:link rel="alternate" hreflang="de" href="http://localhost:3000/de" />
+</url>
+<url>
 <loc>http://localhost:3000/en/pathnames</loc>
 <xhtml:link rel="alternate" hreflang="en" href="http://localhost:3000/en/pathnames" />
 <xhtml:link rel="alternate" hreflang="de" href="http://localhost:3000/de/pfadnamen" />
 </url>
+<url>
+<loc>http://localhost:3000/de/pfadnamen</loc>
+<xhtml:link rel="alternate" hreflang="en" href="http://localhost:3000/en/pathnames" />
+<xhtml:link rel="alternate" hreflang="de" href="http://localhost:3000/de/pfadnamen" />
+</url>
 </urlset>
 `
   );

Diff for: lerna.json

@@ -1,6 +1,6 @@
 {
   "$schema": "node_modules/@lerna-lite/cli/schemas/lerna-schema.json",
-  "version": "3.26.3",
+  "version": "3.26.5",
   "packages": [
     "packages/*"
   ],