feat: Add forcePrefix option for redirect and getPathname (#1865)

When using a
[`localePrefix`](https://next-intl.dev/docs/routing#localeprefix)
setting other than `always`, you can now enforce a locale prefix by
setting the `forcePrefix` option to `true`. This is useful when changing
the user's locale and you need to update the [locale
cookie](https://next-intl.dev/docs/routing#locale-cookie) first.

```tsx
// Will initially redirect to `/en/about` to update the locale
// cookie, regardless of your `localePrefix` setting
redirect({href: '/about', locale: 'en', forcePrefix: true});
```

Resolves #1845



→ [Updated docs](https://next-intl.dev/docs/routing/navigation#redirect)

Author: amannn

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

@@ -292,9 +292,9 @@ const pathname = usePathname();
 
 ### `redirect`
 
-If you want to interrupt the render and redirect to another page, you can invoke the `redirect` function. This wraps [the `redirect` function from Next.js](https://nextjs.org/docs/app/api-reference/functions/redirect) and localizes the pathname as necessary.
+If you want to interrupt the render and redirect to another page, you can invoke the `redirect` function. This wraps [`redirect` from Next.js](https://nextjs.org/docs/app/api-reference/functions/redirect) and localizes the pathname as necessary.
 
-Note that a `locale` prop is always required, even if you're just passing [the current locale](/docs/usage/configuration#locale).
+Note that a `locale` prop is always required, even if you're just passing [the current locale](/docs/usage/configuration#use-locale).
 
 ```tsx
 import {redirect} from '@/i18n/navigation';
@@ -306,7 +306,7 @@ redirect({href: '/login', locale: 'en'});
 redirect({href: '/users', query: {sortBy: 'name'}, locale: 'en'});
 ```
 
-Depending on if you're using the pathnames setting, dynamic params can either be passed as:
+Depending on if you're using the [`pathnames`](/docs/routing#pathnames) setting, dynamic params can either be passed as:
 
 ```tsx
 // 1. A final string (when not using `pathnames`)
@@ -322,6 +322,14 @@ redirect({
 });
 ```
 
+When using a [`localePrefix`](/docs/routing#localeprefix) setting other than `always`, you can enforce a locale prefix by setting the `forcePrefix` option to `true`. This is useful when changing the user's locale and you need to update the [locale cookie](/docs/routing#locale-cookie) first:
+
+```tsx
+// Will initially redirect to `/en/about` to update the locale
+// cookie, regardless of your `localePrefix` setting
+redirect({href: '/about', locale: 'en', forcePrefix: true});
+```
+
 <Callout>
   [`permanentRedirect`](https://nextjs.org/docs/app/api-reference/functions/permanentRedirect)
   is supported too.

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

@@ -21,7 +21,7 @@ const config: SizeLimitConfig = [
     name: "import {createNavigation} from 'next-intl/navigation' (react-client)",
     path: 'dist/esm/production/navigation.react-client.js',
     import: '{createNavigation}',
-    limit: '2.305 KB'
+    limit: '2.308 KB'
   },
   {
     name: "import {createNavigation} from 'next-intl/navigation' (react-server)",

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

@@ -759,6 +759,12 @@ describe.each([
         // eslint-disable-next-line @typescript-eslint/no-unused-expressions
         () => getPathname({href: '/about'});
       });
+
+      it('can force a prefix for the default locale', () => {
+        expect(
+          getPathname({locale: 'en', href: '/about', forcePrefix: true})
+        ).toBe('/en/about');
+      });
     });
 
     describe.each([
@@ -781,10 +787,17 @@ describe.each([
         );
         expect(nextRedirectFn).toHaveBeenLastCalledWith('/', RedirectType.push);
       });
+
+      it('can force a prefix for the default locale', () => {
+        runInRender(() =>
+          redirectFn({href: '/', locale: 'en', forcePrefix: true})
+        );
+        expect(nextRedirectFn).toHaveBeenLastCalledWith('/en');
+      });
     });
   });
 
-  describe('localePrefix: "always", with `prefixes`', () => {
+  describe("localePrefix: 'always', with `prefixes`", () => {
     const {Link, getPathname, permanentRedirect, redirect} = createNavigation({
       locales,
       defaultLocale,
@@ -1088,6 +1101,12 @@ describe.each([
         // eslint-disable-next-line @typescript-eslint/no-unused-expressions
         () => getPathname({href: '/about'});
       });
+
+      it('can force a prefix', () => {
+        expect(
+          getPathname({locale: 'en', href: '/about', forcePrefix: true})
+        ).toBe('/en/about');
+      });
     });
 
     describe.each([
@@ -1105,6 +1124,13 @@ describe.each([
         );
         expect(nextRedirectFn).toHaveBeenLastCalledWith('/', RedirectType.push);
       });
+
+      it('can force a prefix', () => {
+        runInRender(() =>
+          redirectFn({href: '/', locale: 'en', forcePrefix: true})
+        );
+        expect(nextRedirectFn).toHaveBeenLastCalledWith('/en');
+      });
     });
   });
 

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

@@ -101,14 +101,13 @@ export default function createSharedNavigationFns<
       : localePromiseOrValue;
 
     const finalPathname = isLocalizable
-      ? getPathname(
-          {
-            locale: locale || curLocale,
-            // @ts-expect-error -- This is ok
-            href: pathnames == null ? pathname : {pathname, params}
-          },
-          locale != null || undefined
-        )
+      ? getPathname({
+          locale: locale || curLocale,
+          // @ts-expect-error -- This is ok
+          href: pathnames == null ? pathname : {pathname, params},
+          // Always include a prefix when changing locales
+          forcePrefix: locale != null || undefined
+        })
       : pathname;
 
     return (
@@ -128,18 +127,17 @@ export default function createSharedNavigationFns<
   }
   const LinkWithRef = forwardRef(Link);
 
-  function getPathname(
-    args: {
-      /** @see https://next-intl.dev/docs/routing/navigation#getpathname */
-      href: [AppPathnames] extends [never]
-        ? string | {pathname: string; query?: QueryParams}
-        : HrefOrHrefWithParams<keyof AppPathnames>;
-      locale: Locale;
-    },
-    /** @private Removed in types returned below */
-    _forcePrefix?: boolean
-  ) {
-    const {href, locale} = args;
+  function getPathname(args: {
+    /** @see https://next-intl.dev/docs/routing/navigation#getpathname */
+    href: [AppPathnames] extends [never]
+      ? string | {pathname: string; query?: QueryParams}
+      : HrefOrHrefWithParams<keyof AppPathnames>;
+    /** The locale to compute the pathname for. */
+    locale: Locale;
+    /** Will prepend the pathname with the locale prefix, regardless of your `localePrefix` setting. This can be helpful to update a locale cookie when changing locales. */
+    forcePrefix?: boolean;
+  }) {
+    const {forcePrefix, href, locale} = args;
 
     let pathname: string;
     if (pathnames == null) {
@@ -161,15 +159,15 @@ export default function createSharedNavigationFns<
       });
     }
 
-    return applyPathnamePrefix(pathname, locale, config, _forcePrefix);
+    return applyPathnamePrefix(pathname, locale, config, forcePrefix);
   }
 
   function getRedirectFn(
     fn: typeof nextRedirect | typeof nextPermanentRedirect
   ) {
     /** @see https://next-intl.dev/docs/routing/navigation#redirect */
     return function redirectFn(
-      args: Omit<Parameters<typeof getPathname>[0], 'domain'>,
+      args: Parameters<typeof getPathname>[0],
       ...rest: ParametersExceptFirst<typeof nextRedirect>
     ) {
       return fn(getPathname(args), ...rest);
@@ -184,10 +182,6 @@ export default function createSharedNavigationFns<
     Link: LinkWithRef,
     redirect,
     permanentRedirect,
-
-    // Remove `_forcePrefix` from public API
-    getPathname: getPathname as (
-      args: Parameters<typeof getPathname>[0]
-    ) => string
+    getPathname
   };
 }