feat: Automatically prefer localized pathnames that are more specific

docs/pages/docs/routing/middleware.mdx

@@ -322,20 +322,19 @@ export default createMiddleware({
       de: '/ueber-uns'
     },
 
-    // Pathnames that overlap with dynamic segments should
-    // be listed first in the object, as the middleware will
-    // pick the first matching entry.
-    '/news/just-in': {
-      en: '/news/just-in',
-      de: '/neuigkeiten/aktuell'
-    },
-
     // Dynamic params are supported via square brackets
     '/news/[articleSlug]-[articleId]': {
       en: '/news/[articleSlug]-[articleId]',
       de: '/neuigkeiten/[articleSlug]-[articleId]'
     },
 
+    // Static pathnames that overlap with dynamic segments
+    // will be prioritized over the dynamic segment
+    '/news/just-in': {
+      en: '/news/just-in',
+      de: '/neuigkeiten/aktuell'
+    },
+
     // Also (optional) catch-all segments are supported
     '/categories/[...slug]': {
       en: '/categories/[...slug]',

examples/example-app-router-playground/messages/de.json

@@ -31,6 +31,9 @@
   "NewsArticle": {
     "title": "News-Artikel #{articleId}"
   },
+  "JustIn": {
+    "title": "Gerade eingetroffen"
+  },
   "NotFound": {
     "title": "Diese Seite wurde nicht gefunden (404)"
   },

examples/example-app-router-playground/messages/en.json

@@ -31,6 +31,9 @@
   "NewsArticle": {
     "title": "News article #{articleId}"
   },
+  "JustIn": {
+    "title": "Just in"
+  },
   "NotFound": {
     "title": "This page was not found (404)"
   },

examples/example-app-router-playground/messages/es.json

@@ -31,6 +31,9 @@
   "NewsArticle": {
     "title": "Noticias #{articleId}"
   },
+  "JustIn": {
+    "title": "Recién llegado"
+  },
   "NotFound": {
     "title": "Esta página no se encontró (404)"
   },

examples/example-app-router-playground/src/app/[locale]/news/just-in/page.tsx

@@ -0,0 +1,6 @@
+import {useTranslations} from 'next-intl';
+
+export default function NewsArticle() {
+  const t = useTranslations('JustIn');
+  return <h1>{t('title')}</h1>;
+}

examples/example-app-router-playground/src/navigation.tsx

@@ -26,6 +26,12 @@ export const pathnames = {
     de: '/neuigkeiten/[articleId]',
     es: '/noticias/[articleId]',
     ja: '/ニュース/[articleId]'
+  },
+  '/news/just-in': {
+    en: '/news/just-in',
+    de: '/neuigkeiten/aktuell',
+    es: '/noticias/justo-en',
+    ja: '/ニュース/現在'
   }
 } satisfies Pathnames<typeof locales>;
 

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

@@ -153,6 +153,24 @@ it('redirects unprefixed paths for non-default locales', async ({browser}) => {
   page.getByRole('heading', {name: 'Verschachtelt'});
 });
 
+it('priotizes static routes over dynamic routes for the default locale', async ({
+  page
+}) => {
+  await page.goto('/news/just-in');
+  await expect(page).toHaveURL('/news/just-in');
+  await expect(page.getByRole('heading', {name: 'Just In'})).toBeVisible();
+});
+
+it('priotizes static routes over dynamic routes for non-default locales', async ({
+  page
+}) => {
+  await page.goto('/de/neuigkeiten/aktuell');
+  await expect(page).toHaveURL('/de/neuigkeiten/aktuell');
+  await expect(
+    page.getByRole('heading', {name: 'Gerade eingetroffen'})
+  ).toBeVisible();
+});
+
 it('sets the `path` for the cookie', async ({page}) => {
   await page.goto('/de/client');
 

packages/next-intl/package.json

@@ -138,7 +138,7 @@
     },
     {
       "path": "dist/production/middleware.js",
-      "limit": "5.95 KB"
+      "limit": "6.10 KB"
     }
   ]
 }

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

@@ -9,6 +9,71 @@ export function getFirstPathnameSegment(pathname: string) {
   return pathname.split('/')[1];
 }
 
+function getExternalPath<Locales extends AllLocales>(
+  path: string | {[Key in Locales[number]]: string}
+): string {
+  const firstLocalePath = Object.values(path)[0];
+  return typeof path === 'string' ? path : firstLocalePath;
+}
+
+function isCatchAllRoute(pathname: string) {
+  return isOptionalCatchAll(pathname) || isCatchAll(pathname);
+}
+
+function isOptionalCatchAll(pathname: string) {
+  return pathname.includes('[[...');
+}
+
+function isCatchAll(pathname: string) {
+  return pathname.includes('[...');
+}
+
+function isDynamicRoute(pathname: string) {
+  return pathname.includes('[');
+}
+
+type PathnamePair<Locales extends AllLocales> = [
+  string,
+  string | {[Key in Locales[number]]: string}
+];
+
+export function comparePathnamePairs<Locales extends AllLocales>(
+  a: PathnamePair<Locales>,
+  b: PathnamePair<Locales>
+): number {
+  const pathA = getExternalPath(a[1]);
+  const pathB = getExternalPath(b[1]);
+
+  const dynamicA = isDynamicRoute(pathA);
+  const dynamicB = isDynamicRoute(pathB);
+  const catchAllA = isCatchAllRoute(pathA);
+  const catchAllB = isCatchAllRoute(pathB);
+
+  // Prioritize static routes over dynamic and catch-all routes
+  if (!dynamicA && dynamicB) return -1;
+  if (dynamicA && !dynamicB) return 1;
+
+  // Both paths are either dynamic or static, prioritize non-catch-all over catch-all
+  if (catchAllA && !catchAllB) return 1;
+  if (!catchAllA && catchAllB) return -1;
+
+  // If both are the same type (static, dynamic non-catch-all, or catch-all), prioritize by depth
+  const depthA = pathA.split('/').length;
+  const depthB = pathB.split('/').length;
+
+  // Deeper (more specific) paths first
+  if (depthA !== depthB) return depthB - depthA;
+
+  return 0;
+}
+
+export function getSortedPathnames<Locales extends AllLocales>(
+  pathnames: NonNullable<MiddlewareConfigWithDefaults<Locales>['pathnames']>
+) {
+  const sortedPathnames = Object.entries(pathnames).sort(comparePathnamePairs);
+  return sortedPathnames;
+}
+
 export function getInternalTemplate<
   Locales extends AllLocales,
   Pathnames extends NonNullable<
@@ -19,10 +84,13 @@ export function getInternalTemplate<
   pathname: string,
   locale: Locales[number]
 ): [Locales[number] | undefined, keyof Pathnames | undefined] {
+  // Sort pathnames by specificity
+  const sortedPathnames = getSortedPathnames(pathnames);
   // Try to find a localized pathname that matches
-  for (const [internalPathname, localizedPathnamesOrPathname] of Object.entries(
-    pathnames
-  )) {
+  for (const [
+    internalPathname,
+    localizedPathnamesOrPathname
+  ] of sortedPathnames) {
     if (typeof localizedPathnamesOrPathname === 'string') {
       const localizedPathname = localizedPathnamesOrPathname;
       if (matchesPathname(localizedPathname, pathname)) {

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

@@ -397,11 +397,29 @@ describe('prefix-based routing', () => {
             'de-AT': '/produkte/[...slug]',
             ja: '/製品/[...slug]'
           },
+          '/products/[slug]': {
+            en: '/products/[slug]',
+            de: '/produkte/[slug]',
+            'de-AT': '/produkte/[slug]',
+            ja: '/製品/[slug]'
+          },
+          '/products/add': {
+            en: '/products/add',
+            de: '/produkte/hinzufuegen',
+            'de-AT': '/produkte/hinzufuegen',
+            ja: '/製品/追加'
+          },
           '/categories/[[...slug]]': {
             en: '/categories/[[...slug]]',
             de: '/kategorien/[[...slug]]',
             'de-AT': '/kategorien/[[...slug]]',
             ja: '/カテゴリー/[[...slug]]'
+          },
+          '/categories/new': {
+            en: '/categories/new',
+            de: '/kategorien/neu',
+            'de-AT': '/kategorien/neu',
+            ja: '/カテゴリー/新着'
           }
         } satisfies Pathnames<ReadonlyArray<'en' | 'de' | 'de-AT' | 'ja'>>
       });
@@ -642,6 +660,36 @@ describe('prefix-based routing', () => {
         );
       });
 
+      it('priotizes static routes over dynamic and catch-all routes for the non-default locale', () => {
+        middlewareWithPathnames(createMockRequest('/products/add', 'en'));
+        middlewareWithPathnames(createMockRequest('/categories/new', 'en'));
+        expect(MockedNextResponse.next).not.toHaveBeenCalled();
+        expect(MockedNextResponse.redirect).not.toHaveBeenCalled();
+        expect(MockedNextResponse.rewrite).toHaveBeenCalledTimes(2);
+        expect(MockedNextResponse.rewrite.mock.calls[0][0].toString()).toBe(
+          'http://localhost:3000/en/products/add'
+        );
+        expect(MockedNextResponse.rewrite.mock.calls[1][0].toString()).toBe(
+          'http://localhost:3000/en/categories/new'
+        );
+      });
+
+      it('priotizes static routes over dynamic and catch-all routes for the non-default locale', () => {
+        middlewareWithPathnames(
+          createMockRequest('/de/produkte/hinzufuegen', 'de')
+        );
+        middlewareWithPathnames(createMockRequest('/de/kategorien/neu', 'de'));
+        expect(MockedNextResponse.next).not.toHaveBeenCalled();
+        expect(MockedNextResponse.redirect).not.toHaveBeenCalled();
+        expect(MockedNextResponse.rewrite).toHaveBeenCalledTimes(2);
+        expect(MockedNextResponse.rewrite.mock.calls[0][0].toString()).toBe(
+          'http://localhost:3000/de/products/add'
+        );
+        expect(MockedNextResponse.rewrite.mock.calls[1][0].toString()).toBe(
+          'http://localhost:3000/de/categories/new'
+        );
+      });
+
       it('sets alternate links', () => {
         function getLinks(request: NextRequest) {
           return middlewareWithPathnames(request)
@@ -1010,10 +1058,22 @@ describe('prefix-based routing', () => {
             en: '/products/[...slug]',
             de: '/produkte/[...slug]'
           },
+          '/products/[slug]': {
+            en: '/products/[slug]',
+            de: '/produkte/[slug]'
+          },
+          '/products/add': {
+            en: '/products/add',
+            de: '/produkte/hinzufuegen'
+          },
           '/categories/[[...slug]]': {
             en: '/categories/[[...slug]]',
             de: '/kategorien/[[...slug]]'
           },
+          '/categories/new': {
+            en: '/categories/new',
+            de: '/kategorien/neu'
+          },
           '/internal': '/external',
           '/internal/foo/bar': {
             en: '/external-en/foo/bar',
@@ -1100,10 +1160,40 @@ describe('prefix-based routing', () => {
           'http://localhost:3000/de/users/1',
           'http://localhost:3000/de/news/gutes-neues-jahr-g5b116754',
           'http://localhost:3000/de/categories',
-          'http://localhost:3000/de/categories/neu'
+          'http://localhost:3000/de/categories/new'
         ]);
       });
 
+      it('priotizes static routes over dynamic and catch-all routes for the default locale', () => {
+        middlewareWithPathnames(createMockRequest('/en/products/add', 'en'));
+        middlewareWithPathnames(createMockRequest('/en/categories/new', 'en'));
+        expect(MockedNextResponse.next).not.toHaveBeenCalled();
+        expect(MockedNextResponse.redirect).not.toHaveBeenCalled();
+        expect(MockedNextResponse.rewrite).toHaveBeenCalledTimes(2);
+        expect(MockedNextResponse.rewrite.mock.calls[0][0].toString()).toBe(
+          'http://localhost:3000/en/products/add'
+        );
+        expect(MockedNextResponse.rewrite.mock.calls[1][0].toString()).toBe(
+          'http://localhost:3000/en/categories/new'
+        );
+      });
+
+      it('priotizes static routes over dynamic and catch-all routes for the non-default locale', () => {
+        middlewareWithPathnames(
+          createMockRequest('/de/produkte/hinzufuegen', 'de')
+        );
+        middlewareWithPathnames(createMockRequest('/de/kategorien/neu', 'de'));
+        expect(MockedNextResponse.next).not.toHaveBeenCalled();
+        expect(MockedNextResponse.redirect).not.toHaveBeenCalled();
+        expect(MockedNextResponse.rewrite).toHaveBeenCalledTimes(2);
+        expect(MockedNextResponse.rewrite.mock.calls[0][0].toString()).toBe(
+          'http://localhost:3000/de/products/add'
+        );
+        expect(MockedNextResponse.rewrite.mock.calls[1][0].toString()).toBe(
+          'http://localhost:3000/de/categories/new'
+        );
+      });
+
       it('redirects a request for a localized route that is not associated with the requested locale', () => {
         // Relevant to avoid duplicate content issues
         middlewareWithPathnames(createMockRequest('/en/ueber', 'en'));