feat!: Stricter config for domains to improve handling of localePrefix: 'as-needed' (#1734)

So far, when using
[`domains`](https://next-intl.dev/docs/routing#domains) in combination
with `localePrefix: 'as-needed'`, `next-intl` had to make some
[tradeoffs](https://next-intl-docs-6wwcmwb9a-next-intl.vercel.app/docs/routing#domains-localeprefix-asneeded).

Now, `next-intl` comes with stricter requirements when `domains` is
used:
1. A locale can now only be used for a single domain
2. Each domain now must specify its `locales`

By introducing these constraints, the mentioned tradeoffs now can be
removed altogether, resulting in a simplified model.

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.

**Before**

```tsx
import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  locales: ['sv', 'en', 'no', 'fr'],
  defaultLocale: 'en',
  localePrefix: 'as-needed',
  domains: [
    {
      domain: 'domain.se',
      defaultLocale: 'sv',
      locales: ['sv', 'en']      
    },
    {
      domain: 'domain.no',
      defaultLocale: 'no',
      locales: ['no', 'en']
    },
    {
      domain: 'domain.com',
      defaultLocale: 'en',
      locales: ['en', 'fr']
    },
  ]
});
```

**After**

```tsx
import {defineRouting} from 'next-intl/routing';
 
export const routing = defineRouting({
  locales: ['sv-SE', 'en-SE', 'no-NO', 'en-NO', 'fr-FR', 'en-US'],
  defaultLocale: 'en-US',
  localePrefix: {
    mode: 'as-needed',
    prefixes: {
      'en-SE': '/en',
      'en-NO': '/en',
      'en-US': '/en',
      'fr-FR': '/fr'
    }
  },
  domains: [
    {
      domain: 'domain.se',
      defaultLocale: 'sv-SE',
      locales: ['sv-SE', 'en-SE']      
    },
    {
      domain: 'domain.no',
      defaultLocale: 'no-NO',
      locales: ['no-NO', 'en-NO']
    },
    {
      domain: 'domain.com',
      defaultLocale: 'en-US',
      locales: ['en-US', 'fr-FR']
    },
  ]
});
```

Learn more in the updated docs for
[`domains`](https://v4.next-intl.dev/docs/routing#domains).



Resolves #1733

**TODO**
- [x] Docs
- [x] Implementation
- [x] Real world test and make sure we don't have any problems with
prefixes
- [ ] When users have more locales,
#990 would be really handy
- [ ] Back-port warning to v3 (also that locales are becoming unique per
domain)
- [ ] Update blog post

Author: amannn

docs/src/pages/docs/routing.mdx

@@ -321,37 +321,49 @@ If you want to serve your localized content based on different domains, you can
 
 **Examples:**
 
-- `us.example.com/en`
-- `ca.example.com/en`
-- `ca.example.com/fr`
+- `us.example.com`: `en-US`
+- `ca.example.com`: `en-CA`
+- `ca.example.com/fr`: `fr-CA`
+- `fr.example.com`: `fr-FR`
+
+In many cases, `domains` are combined with a [`localePrefix`](#locale-prefix) setting to achieve results as shown above. Also [custom prefixes](#locale-prefix-custom) can be used to customize the user-facing prefix per locale.
 
 ```tsx filename="routing.ts"
 import {defineRouting} from 'next-intl/routing';
 
 export const routing = defineRouting({
-  locales: ['en', 'fr'],
-  defaultLocale: 'en',
+  locales: ['en-US', 'en-CA', 'fr-CA', 'fr-FR'],
+  defaultLocale: 'en-US',
   domains: [
     {
       domain: 'us.example.com',
-      defaultLocale: 'en',
-      // Optionally restrict the locales available on this domain
-      locales: ['en']
+      defaultLocale: 'en-US',
+      locales: ['en-US']
     },
     {
       domain: 'ca.example.com',
-      defaultLocale: 'en'
-      // If there are no `locales` specified on a domain,
-      // all available locales will be supported here
+      defaultLocale: 'en-CA',
+      locales: ['en-CA', 'fr-CA']
+    },
+    {
+      domain: 'fr.example.com',
+      defaultLocale: 'fr-FR',
+      locales: ['fr-FR']
     }
-  ]
+  ],
+  localePrefix: {
+    mode: 'as-needed',
+    prefixes: {
+      // Cleaner prefix for `ca.example.com/fr`
+      'fr-CA': '/fr'
+    }
+  }
 });
 ```
 
-**Note that:**
+Locales are required to be unique across domains, therefore regional variants are typically used to avoid conflicts. Note however that you don't necessarily need to [provide messages for each locale](/docs/usage/configuration#messages-per-locale) if the overall language is sufficient for your use case.
 
-1. You can optionally remove the locale prefix in pathnames by changing the [`localePrefix`](#locale-prefix) setting. E.g. [`localePrefix: 'never'`](#locale-prefix-never) can be helpful in case you have unique domains per locale.
-2. If no domain matches, the middleware will fall back to the [`defaultLocale`](/docs/routing/middleware#default-locale) (e.g. on `localhost`).
+If no domain matches, the middleware will fall back to the general [`defaultLocale`](/docs/routing/middleware#default-locale) (e.g. on `localhost`).
 
 <Details id="domains-testing">
 <summary>How can I locally test if my setup is working?</summary>
@@ -393,9 +405,7 @@ PORT=3001 npm run dev
 <Details id="domains-localeprefix-individual">
 <summary>Can I use a different `localePrefix` setting per domain?</summary>
 
-Since such a configuration would require reading the domain at runtime, this would prevent the ability to render pages statically. Due to this, `next-intl` doesn't support this configuration out of the box.
-
-However, you can still achieve this by building the app for each domain separately, while injecting diverging routing configuration via an environment variable.
+While this is currently not supported out of the box, you can still achieve this by building the app for each domain separately while injecting diverging routing configuration via an environment variable.
 
 **Example:**
 
@@ -406,48 +416,14 @@ const isUsDomain =
   process.env.VERCEL_PROJECT_PRODUCTION_URL === 'us.example.com';
 
 export const routing = defineRouting({
-  locales: isUsDomain ? ['en'] : ['en', 'fr'],
-  defaultLocale: 'en',
+  locales: isUsDomain ? ['en-US'] : ['en-CA', 'fr-CA'],
+  defaultLocale: isUsDomain ? 'en-US' : 'en-CA',
   localePrefix: isUsDomain ? 'never' : 'always'
 });
 ```
 
 </Details>
 
-<Details id="domains-localeprefix-asneeded">
-<summary>Special case: Using `domains` with `localePrefix: 'as-needed'`</summary>
-
-Since domains can have different default locales, this combination requires some tradeoffs that apply to the [navigation APIs](/docs/routing/navigation) in order for `next-intl` to avoid reading the current host on the server side (which would prevent the usage of static rendering).
-
-1. [`<Link />`](/docs/routing/navigation#link): This component will always render a locale prefix on the server side, even for the default locale of a given domain. However, during hydration on the client side, the prefix is potentially removed, if the default locale of the current domain is used. Note that the temporarily prefixed pathname will always be valid, however the middleware will potentially clean up a superfluous prefix via a redirect if the user clicks on a link before hydration.
-2. [`redirect`](/docs/routing/navigation#redirect): When calling this function, a locale prefix is always added, regardless of the provided locale. However, similar to the handling with `<Link />`, the middleware will potentially clean up a superfluous prefix.
-3. [`getPathname`](/docs/routing/navigation#getpathname): This function requires that a `domain` is passed as part of the arguments in order to avoid ambiguity. This can either be provided statically (e.g. when used in a sitemap), or read from a header like [`x-forwarded-host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host).
-
-```tsx
-import {getPathname} from '@/i18n/routing';
-import {headers} from 'next/headers';
-
-// Case 1: Statically known domain
-const domain = 'ca.example.com';
-
-// Case 2: Read at runtime (dynamic rendering)
-const domain = headers().get('x-forwarded-host');
-
-// Assuming the current domain is `ca.example.com`,
-// the returned pathname will be `/about`
-const pathname = getPathname({
-  href: '/about',
-  locale: 'en',
-  domain
-});
-```
-
-A `domain` can optionally also be passed to `redirect` in the same manner to ensure that a prefix is only added when necessary. Alternatively, you can also consider redirecting in the middleware or via [`useRouter`](/docs/routing/navigation#usrouter) on the client side.
-
-If you need to avoid these tradeoffs, you can consider building the same app for each domain separately, while injecting diverging routing configuration via an [environment variable](#domains-localeprefix-individual).
-
-</Details>
-
 ### Turning off locale detection [#locale-detection]
 
 The middleware will [detect a matching locale](/docs/routing/middleware#locale-detection) based on your routing configuration and the incoming request.

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

@@ -93,14 +93,13 @@ Since the middleware is aware of all your domains, if a domain receives a reques
 4. The middleware recognizes that the user wants to switch to another domain and responds with a redirect to `ca.example.com/fr`.
 
 <Details id="domain-matching">
-<summary>How is the best matching domain for a given locale detected?</summary>
+<summary>How is the best-matching domain for a given locale detected?</summary>
 
-The bestmatching domain is detected based on these priorities:
+The best-matching domain is detected based on these priorities:
 
 1. Stay on the current domain if the locale is supported here
 2. Use an alternative domain where the locale is configured as the `defaultLocale`
-3. Use an alternative domain where the available `locales` are restricted and the locale is supported
-4. Use an alternative domain that supports all locales
+3. Use an alternative domain that supports the locale
 
 </Details>
 

docs/src/pages/docs/usage/configuration.mdx

@@ -358,6 +358,30 @@ Note that [the VSCode integration for `next-intl`](/docs/workflows/vscode-integr
 
 </Details>
 
+<Details id="messages-per-locale">
+<summary>Do I need separate messages for each locale that my app supports?</summary>
+
+Since you have full control over how messages are loaded, you can choose to load messages for example merely based on the overall language, ignoring any regional variants:
+
+```tsx
+import {getRequestConfig} from 'next-intl/server';
+
+export default getRequestConfig(async () => {
+  // E.g. "en-US", "en-CA", …
+  const locale = 'en-US';
+
+  // E.g. "en"
+  const language = new Intl.Locale(locale).language;
+
+  // Load messages based on the language
+  const messages = (await import(`../../messages/${language}.json`)).default;
+
+  // ...
+});
+```
+
+</Details>
+
 ### `useMessages` & `getMessages` [#use-messages]
 
 In case you require access to messages in a component, you can read them via `useMessages()` or `getMessages()` from your configuration:

examples/example-app-router-playground/src/i18n/routing.ts

@@ -18,11 +18,13 @@ export const routing = defineRouting({
       ? [
           {
             domain: 'example.com',
-            defaultLocale: 'en'
+            defaultLocale: 'en',
+            locales: ['en', 'es', 'ja']
           },
           {
             domain: 'example.de',
-            defaultLocale: 'de'
+            defaultLocale: 'de',
+            locales: ['de']
           }
         ]
       : undefined,

examples/example-app-router-playground/tests/domains.spec.ts

@@ -37,6 +37,5 @@ it('can use a secondary locale unprefixed if the domain has specified it as the
   await page.getByRole('link', {name: 'Start'}).click();
   await expect(page).toHaveURL('http://example.de');
   await page.getByRole('link', {name: 'Zu Englisch wechseln'}).click();
-  await expect(page).toHaveURL('http://example.de/en');
-  await expect(page.getByRole('heading', {name: 'Home'})).toBeVisible();
+  await expect(page).toHaveURL('http://example.com/en');
 });

packages/next-intl/.size-limit.ts

@@ -21,13 +21,13 @@ const config: SizeLimitConfig = [
     name: "import {createNavigation} from 'next-intl/navigation' (react-client)",
     path: 'dist/esm/production/navigation.react-client.js',
     import: '{createNavigation}',
-    limit: '2.485 KB'
+    limit: '2.285 KB'
   },
   {
     name: "import {createNavigation} from 'next-intl/navigation' (react-server)",
     path: 'dist/esm/production/navigation.react-server.js',
     import: '{createNavigation}',
-    limit: '3.275 KB'
+    limit: '3.055 KB'
   },
   {
     name: "import * from 'next-intl/server' (react-client)",
@@ -42,7 +42,7 @@ const config: SizeLimitConfig = [
   {
     name: "import * from 'next-intl/middleware'",
     path: 'dist/esm/production/middleware.js',
-    limit: '9.315 KB'
+    limit: '9.355 KB'
   },
   {
     name: "import * from 'next-intl/routing'",

packages/next-intl/src/middleware/getAlternateLinksHeaderValue.test.tsx

@@ -197,8 +197,8 @@ describe.each([{basePath: undefined}, {basePath: '/base'}])(
         domains: [
           {
             domain: 'example.com',
-            defaultLocale: 'en'
-            // (supports all locales)
+            defaultLocale: 'en',
+            locales: ['en', 'es', 'fr']
           },
           {
             domain: 'example.es',
@@ -264,8 +264,8 @@ describe.each([{basePath: undefined}, {basePath: '/base'}])(
         domains: [
           {
             domain: 'example.com',
-            defaultLocale: 'en'
-            // (supports all locales)
+            defaultLocale: 'en',
+            locales: ['en', 'es', 'fr']
           },
           {
             domain: 'example.es',

packages/next-intl/src/middleware/middleware.test.tsx

@@ -2480,7 +2480,8 @@ describe('domain-based routing', () => {
         domains: [
           {
             defaultLocale: 'fr',
-            domain: 'ca.example.com'
+            domain: 'ca.example.com',
+            locales: ['en', 'fr']
           }
         ]
       });
@@ -3193,20 +3194,73 @@ describe('domain-based routing', () => {
     describe('custom prefixes with pathnames', () => {
       const middlewareWithPrefixes = createMiddleware({
         defaultLocale: 'en',
-        locales: ['en', 'en-gb'],
+        locales: ['en', 'en-gb', 'sv-SE', 'en-SE', 'no-NO', 'en-NO'],
         localePrefix: {
           mode: 'as-needed',
           prefixes: {
-            'en-gb': '/uk'
+            'en-gb': '/uk',
+            'en-SE': '/en',
+            'en-NO': '/en'
           }
         },
         pathnames: {
           '/': '/',
           '/about': {
             en: '/about',
-            'en-gb': '/about'
+            'en-gb': '/about',
+            'en-SE': '/about',
+            'en-NO': '/about',
+            'sv-SE': '/about',
+            'no-NO': '/about'
+          }
+        } satisfies Pathnames<
+          ReadonlyArray<'en' | 'en-gb' | 'sv-SE' | 'en-SE' | 'no-NO' | 'en-NO'>
+        >,
+        domains: [
+          {
+            defaultLocale: 'en-gb',
+            domain: 'example.co.uk',
+            locales: ['en-gb']
+          },
+          {
+            defaultLocale: 'sv-SE',
+            domain: 'example.se',
+            locales: ['sv-SE', 'en-SE']
+          },
+          {
+            defaultLocale: 'no-NO',
+            domain: 'example.no',
+            locales: ['no-NO', 'en-NO']
+          },
+          {
+            defaultLocale: 'en',
+            domain: 'example.com',
+            locales: ['en']
           }
-        } satisfies Pathnames<ReadonlyArray<'en' | 'en-gb'>>
+        ]
+      });
+
+      it('serves requests for overlapping prefixes', () => {
+        middlewareWithPrefixes(
+          createMockRequest('/', undefined, 'http://example.com')
+        );
+        middlewareWithPrefixes(
+          createMockRequest('/en', undefined, 'http://example.no')
+        );
+        middlewareWithPrefixes(
+          createMockRequest('/en', undefined, 'http://example.se')
+        );
+        expect(MockedNextResponse.redirect).not.toHaveBeenCalled();
+        expect(MockedNextResponse.rewrite).toHaveBeenCalledTimes(3);
+        expect(MockedNextResponse.rewrite.mock.calls[0][0].toString()).toBe(
+          'http://example.com/en'
+        );
+        expect(MockedNextResponse.rewrite.mock.calls[1][0].toString()).toBe(
+          'http://example.no/en-NO'
+        );
+        expect(MockedNextResponse.rewrite.mock.calls[2][0].toString()).toBe(
+          'http://example.se/en-SE'
+        );
       });
 
       it('serves requests for the default locale at the root', () => {
@@ -3256,24 +3310,33 @@ describe('domain-based routing', () => {
 
         ['/', '/uk'].forEach((pathname) => {
           expect(getLinks(createMockRequest(pathname))).toEqual([
-            '<http://localhost:3000/>; rel="alternate"; hreflang="en"',
-            '<http://localhost:3000/uk>; rel="alternate"; hreflang="en-gb"',
-            '<http://localhost:3000/>; rel="alternate"; hreflang="x-default"'
+            '<http://example.com/>; rel="alternate"; hreflang="en"',
+            '<http://example.co.uk/>; rel="alternate"; hreflang="en-gb"',
+            '<http://example.se/>; rel="alternate"; hreflang="sv-SE"',
+            '<http://example.se/en>; rel="alternate"; hreflang="en-SE"',
+            '<http://example.no/>; rel="alternate"; hreflang="no-NO"',
+            '<http://example.no/en>; rel="alternate"; hreflang="en-NO"'
           ]);
         });
 
         ['/about', '/uk/about'].forEach((pathname) => {
           expect(getLinks(createMockRequest(pathname))).toEqual([
-            '<http://localhost:3000/about>; rel="alternate"; hreflang="en"',
-            '<http://localhost:3000/uk/about>; rel="alternate"; hreflang="en-gb"',
-            '<http://localhost:3000/about>; rel="alternate"; hreflang="x-default"'
+            '<http://example.com/about>; rel="alternate"; hreflang="en"',
+            '<http://example.co.uk/about>; rel="alternate"; hreflang="en-gb"',
+            '<http://example.se/about>; rel="alternate"; hreflang="sv-SE"',
+            '<http://example.se/en/about>; rel="alternate"; hreflang="en-SE"',
+            '<http://example.no/about>; rel="alternate"; hreflang="no-NO"',
+            '<http://example.no/en/about>; rel="alternate"; hreflang="en-NO"'
           ]);
         });
 
         expect(getLinks(createMockRequest('/unknown'))).toEqual([
-          '<http://localhost:3000/unknown>; rel="alternate"; hreflang="en"',
-          '<http://localhost:3000/uk/unknown>; rel="alternate"; hreflang="en-gb"',
-          '<http://localhost:3000/unknown>; rel="alternate"; hreflang="x-default"'
+          '<http://example.com/unknown>; rel="alternate"; hreflang="en"',
+          '<http://example.co.uk/unknown>; rel="alternate"; hreflang="en-gb"',
+          '<http://example.se/unknown>; rel="alternate"; hreflang="sv-SE"',
+          '<http://example.se/en/unknown>; rel="alternate"; hreflang="en-SE"',
+          '<http://example.no/unknown>; rel="alternate"; hreflang="no-NO"',
+          '<http://example.no/en/unknown>; rel="alternate"; hreflang="en-NO"'
         ]);
       });
     });

packages/next-intl/src/middleware/middleware.tsx

@@ -152,7 +152,8 @@ export default function createMiddleware<
     const pathnameMatch = getPathnameMatch(
       externalPathname,
       resolvedRouting.locales,
-      resolvedRouting.localePrefix
+      resolvedRouting.localePrefix,
+      domain
     );
     const hasLocalePrefix = pathnameMatch != null;