fix: Don't encode hashes in unknown pathnames

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.325 KB'
+    limit: '2.335 KB'
   },
   {
     name: "import {createNavigation} from 'next-intl/navigation' (react-server)",
     path: 'dist/esm/production/navigation.react-server.js',
     import: '{createNavigation}',
-    limit: '3.095 KB'
+    limit: '3.115 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.645 KB'
+    limit: '9.695 KB'
   },
   {
     name: "import * from 'next-intl/routing'",

packages/next-intl/src/navigation/createNavigation.test.tsx

@@ -572,6 +572,12 @@ describe.each([
         expect(markup).toContain('href="/en/test"');
       });
 
+      it('handles unknown pathnames with a hash', () => {
+        // @ts-expect-error -- Validation is still on
+        const markup = renderToString(<Link href="/test#foo">Test</Link>);
+        expect(markup).toContain('href="/en/test#foo"');
+      });
+
       it('handles external links correctly', () => {
         const markup = renderToString(
           // @ts-expect-error -- Validation is still on

packages/next-intl/src/navigation/shared/utils.tsx

@@ -123,51 +123,48 @@ export function compileLocalizedPathname<AppLocales extends Locales, Pathname>({
   pathnames: Pathnames<AppLocales>;
   query?: Record<string, SearchParamValue>;
 }) {
-  function getNamedPath(value: keyof typeof pathnames) {
-    let namedPath = pathnames[value];
-    if (!namedPath) {
-      // Unknown pathnames
-      namedPath = value;
-    }
-    return namedPath;
-  }
+  function compilePath(value: string) {
+    const pathnameConfig = pathnames[value];
 
-  function compilePath(
-    namedPath: Pathnames<AppLocales>[keyof Pathnames<AppLocales>],
-    internalPathname: string
-  ) {
-    const template = getLocalizedTemplate(namedPath, locale, internalPathname);
-    let compiled = template;
+    let compiled: string;
+    if (pathnameConfig) {
+      const template = getLocalizedTemplate(pathnameConfig, locale, value);
+      compiled = template;
 
-    if (params) {
-      Object.entries(params).forEach(([key, value]) => {
-        let regexp: string, replacer: string;
+      if (params) {
+        Object.entries(params).forEach(([key, paramValue]) => {
+          let regexp: string, replacer: string;
 
-        if (Array.isArray(value)) {
-          regexp = `(\\[)?\\[...${key}\\](\\])?`;
-          replacer = value.map((v) => String(v)).join('/');
-        } else {
-          regexp = `\\[${key}\\]`;
-          replacer = String(value);
-        }
+          if (Array.isArray(paramValue)) {
+            regexp = `(\\[)?\\[...${key}\\](\\])?`;
+            replacer = paramValue.map((v) => String(v)).join('/');
+          } else {
+            regexp = `\\[${key}\\]`;
+            replacer = String(paramValue);
+          }
 
-        compiled = compiled.replace(new RegExp(regexp, 'g'), replacer);
-      });
-    }
+          compiled = compiled.replace(new RegExp(regexp, 'g'), replacer);
+        });
+      }
+
+      // Clean up optional catch-all segments that were not replaced
+      compiled = compiled.replace(/\[\[\.\.\..+\]\]/g, '');
+      if (process.env.NODE_ENV !== 'production' && compiled.includes('[')) {
+        // Next.js throws anyway, therefore better provide a more helpful error message
+        throw new Error(
+          `Insufficient params provided for localized pathname.\nTemplate: ${template}\nParams: ${JSON.stringify(
+            params
+          )}`
+        );
+      }
 
-    // Clean up optional catch-all segments that were not replaced
-    compiled = compiled.replace(/\[\[\.\.\..+\]\]/g, '');
-    if (process.env.NODE_ENV !== 'production' && compiled.includes('[')) {
-      // Next.js throws anyway, therefore better provide a more helpful error message
-      throw new Error(
-        `Insufficient params provided for localized pathname.\nTemplate: ${template}\nParams: ${JSON.stringify(
-          params
-        )}`
-      );
+      compiled = encodePathname(compiled);
+    } else {
+      // Unknown pathnames
+      compiled = value;
     }
 
     compiled = normalizeTrailingSlash(compiled);
-    compiled = encodePathname(compiled);
 
     if (query) {
       // This also encodes non-ASCII characters by
@@ -179,13 +176,10 @@ export function compileLocalizedPathname<AppLocales extends Locales, Pathname>({
   }
 
   if (typeof pathname === 'string') {
-    const namedPath = getNamedPath(pathname);
-    const compiled = compilePath(namedPath, pathname);
-    return compiled;
+    return compilePath(pathname);
   } else {
     const {pathname: internalPathname, ...rest} = pathname;
-    const namedPath = getNamedPath(internalPathname);
-    const compiled = compilePath(namedPath, internalPathname);
+    const compiled = compilePath(internalPathname);
     const result: UrlObject = {...rest, pathname: compiled};
     return result;
   }

packages/next-intl/src/shared/utils.test.tsx

@@ -1,8 +1,9 @@
-import {describe, expect, it} from 'vitest';
+import {beforeEach, describe, expect, it} from 'vitest';
 import {
   getSortedPathnames,
   hasPathnamePrefixed,
   matchesPathname,
+  normalizeTrailingSlash,
   prefixPathname,
   unprefixPathname
 } from './utils.js';
@@ -173,3 +174,60 @@ describe('getSortedPathnames', () => {
     ]);
   });
 });
+
+describe('normalizeTrailingSlash', () => {
+  describe('with trailing slash enabled', () => {
+    beforeEach(() => {
+      process.env._next_intl_trailing_slash = 'true';
+      return () => {
+        delete process.env._next_intl_trailing_slash;
+      };
+    });
+
+    it('should add trailing slash when pathname does not end with slash', () => {
+      expect(normalizeTrailingSlash('/about')).toBe('/about/');
+    });
+
+    it('should not modify pathname when it already ends with slash', () => {
+      expect(normalizeTrailingSlash('/about/')).toBe('/about/');
+    });
+
+    it('should not modify root path', () => {
+      expect(normalizeTrailingSlash('/')).toBe('/');
+    });
+
+    it('should handle pathnames with multiple segments', () => {
+      expect(
+        normalizeTrailingSlash('/categories/development/programming/')
+      ).toBe('/categories/development/programming/');
+    });
+
+    it('handles pathnames that contain a hash', () => {
+      expect(normalizeTrailingSlash('/about#section')).toBe('/about/#section');
+    });
+  });
+
+  describe('with trailing slash disabled', () => {
+    it('should remove trailing slash when pathname ends with slash', () => {
+      expect(normalizeTrailingSlash('/about/')).toBe('/about');
+    });
+
+    it('should not modify pathname when it already has no trailing slash', () => {
+      expect(normalizeTrailingSlash('/about')).toBe('/about');
+    });
+
+    it('should not modify root path', () => {
+      expect(normalizeTrailingSlash('/')).toBe('/');
+    });
+
+    it('should handle pathnames with multiple segments', () => {
+      expect(
+        normalizeTrailingSlash('/categories/development/programming/')
+      ).toBe('/categories/development/programming');
+    });
+
+    it('handles pathnames that contain a hash', () => {
+      expect(normalizeTrailingSlash('/about#section')).toBe('/about#section');
+    });
+  });
+});

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

@@ -72,16 +72,24 @@ export function getLocalizedTemplate<AppLocales extends Locales>(
 export function normalizeTrailingSlash(pathname: string) {
   const trailingSlash = hasTrailingSlash();
 
-  if (pathname !== '/') {
-    const pathnameEndsWithSlash = pathname.endsWith('/');
+  const [path, ...hashParts] = pathname.split('#');
+  const hash = hashParts.join('#');
+
+  let normalizedPath = path;
+  if (normalizedPath !== '/') {
+    const pathnameEndsWithSlash = normalizedPath.endsWith('/');
     if (trailingSlash && !pathnameEndsWithSlash) {
-      pathname += '/';
+      normalizedPath += '/';
     } else if (!trailingSlash && pathnameEndsWithSlash) {
-      pathname = pathname.slice(0, -1);
+      normalizedPath = normalizedPath.slice(0, -1);
     }
   }
 
-  return pathname;
+  if (hash) {
+    normalizedPath += '#' + hash;
+  }
+
+  return normalizedPath;
 }
 
 export function matchesPathname(