fix: Prefix pathnames when switching with useRouter to another locale (#2021)

Fixes #2020

Author: amannn

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

@@ -9,7 +9,7 @@ import AsyncComponentWithNamespaceAndLocale from '../../components/AsyncComponen
 import AsyncComponentWithoutNamespace from '../../components/AsyncComponentWithoutNamespace';
 import AsyncComponentWithoutNamespaceAndLocale from '../../components/AsyncComponentWithoutNamespaceAndLocale';
 import ClientLink from '../../components/ClientLink';
-import ClientRouterWithoutProvider from '../../components/ClientRouterWithoutProvider';
+import ClientRouter from '../../components/ClientRouter';
 import CoreLibrary from '../../components/CoreLibrary';
 import LocaleSwitcher from '../../components/LocaleSwitcher';
 import PageLayout from '../../components/PageLayout';
@@ -50,7 +50,7 @@ export default function Index(props: Props) {
       <MessagesAsPropsCounter />
       <MessagesOnClientCounter />
       <CoreLibrary />
-      <ClientRouterWithoutProvider />
+      <ClientRouter />
       <div>
         <Link href={{pathname: '/', query: {test: true}}}>
           Go to home with query param

…mponents/ClientRouterWithoutProvider.tsx …ayground/src/components/ClientRouter.tsxexamples/example-app-router-playground/src/components/ClientRouterWithoutProvider.tsx renamed to examples/example-app-router-playground/src/components/ClientRouter.tsx examples/example-app-router-playground/src/components/ClientRouterWithoutProvider.tsx renamed to examples/example-app-router-playground/src/components/ClientRouter.tsx

@@ -2,19 +2,15 @@
 
 import {useRouter} from '@/i18n/navigation';
 
-export default function ClientRouterWithoutProvider() {
+export default function ClientRouter() {
   const router = useRouter();
 
   function onClick() {
     router.push('/nested');
   }
 
   return (
-    <button
-      data-testid="ClientRouterWithoutProvider-link"
-      onClick={onClick}
-      type="button"
-    >
+    <button data-testid="ClientRouter-link" onClick={onClick} type="button">
       Go to nested page
     </button>
   );

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

@@ -469,15 +469,15 @@ it('can navigate between sibling pages that share a parent layout', async ({
 
 it('prefixes routes as necessary with the router', async ({page}) => {
   await page.goto('/');
-  page.getByTestId('ClientRouterWithoutProvider-link').click();
+  page.getByTestId('ClientRouter-link').click();
   await expect(page).toHaveURL('/nested');
 
   await page.goto('/en');
-  page.getByTestId('ClientRouterWithoutProvider-link').click();
+  page.getByTestId('ClientRouter-link').click();
   await expect(page).toHaveURL('/nested');
 
   await page.goto('/de');
-  page.getByTestId('ClientRouterWithoutProvider-link').click();
+  page.getByTestId('ClientRouter-link').click();
   await expect(page).toHaveURL('/de/verschachtelt');
 });
 

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

@@ -480,7 +480,7 @@ describe("localePrefix: 'always', custom `prefixes`", () => {
 });
 
 describe("localePrefix: 'as-needed'", () => {
-  const {usePathname, useRouter} = createNavigation({
+  const {Link, usePathname, useRouter} = createNavigation({
     locales,
     defaultLocale,
     localePrefix: 'as-needed'
@@ -493,6 +493,20 @@ describe("localePrefix: 'as-needed'", () => {
     render(<Component />);
   }
 
+  describe('Link', () => {
+    it('sets a cookie when switching to the default locale', () => {
+      mockCurrentLocale('de');
+      global.document.cookie = 'NEXT_LOCALE=de';
+      render(
+        <Link href="/" locale="en">
+          Test
+        </Link>
+      );
+      fireEvent.click(screen.getByRole('link', {name: 'Test'}));
+      expect(document.cookie).toContain('NEXT_LOCALE=en');
+    });
+  });
+
   describe('useRouter', () => {
     const invokeRouter = getInvokeRouter(useRouter);
 
@@ -514,9 +528,16 @@ describe("localePrefix: 'as-needed'", () => {
         expect(useNextRouter()[method]).toHaveBeenCalledWith('/de/about');
       });
 
-      it('does not prefix the default locale when being switched to', () => {
+      it('does prefix the default locale when being switched to', () => {
         invokeRouter((router) => router[method]('/about', {locale: 'en'}));
-        expect(useNextRouter()[method]).toHaveBeenCalledWith('/about');
+        expect(useNextRouter()[method]).toHaveBeenCalledWith('/en/about');
+      });
+
+      it('sets a cookie when switching to the default locale', () => {
+        global.document.cookie = 'NEXT_LOCALE=de';
+        mockCurrentLocale('de');
+        invokeRouter((router) => router[method]('/about', {locale: 'en'}));
+        expect(document.cookie).toContain('NEXT_LOCALE=en');
       });
     });
 
@@ -606,7 +627,7 @@ describe("localePrefix: 'as-needed', with `basePath` and `domains`", () => {
     it('can compute the correct pathname when on a secondary locale and navigating to the default locale', () => {
       mockCurrentLocale('ja');
       invokeRouter((router) => router.push('/test', {locale: 'en'}));
-      expect(useNextRouter().push).toHaveBeenCalledWith('/test');
+      expect(useNextRouter().push).toHaveBeenCalledWith('/en/test');
     });
   });
 });
@@ -737,9 +758,9 @@ describe("localePrefix: 'never'", () => {
         expect(useNextRouter()[method]).toHaveBeenCalledWith('/about');
       });
 
-      it('does not prefix a secondary locale', () => {
+      it('does prefix a pathname when switching to another locale', () => {
         invokeRouter((router) => router[method]('/about', {locale: 'de'}));
-        expect(useNextRouter()[method]).toHaveBeenCalledWith('/about');
+        expect(useNextRouter()[method]).toHaveBeenCalledWith('/de/about');
       });
     });
 
@@ -771,9 +792,9 @@ describe("localePrefix: 'never'", () => {
         expect(useNextRouter().prefetch).toHaveBeenCalledWith('/about');
       });
 
-      it('does not prefix a secondary locale', () => {
+      it('does prefix a pathname when switching to another locale', () => {
         invokeRouter((router) => router.prefetch('/about', {locale: 'de'}));
-        expect(useNextRouter().prefetch).toHaveBeenCalledWith('/about');
+        expect(useNextRouter().prefetch).toHaveBeenCalledWith('/de/about');
       });
     });
   });

packages/next-intl/src/navigation/react-client/createNavigation.tsx

@@ -87,7 +87,14 @@ export default function createNavigation<
 
           const pathname = getPathname({
             href,
-            locale: nextLocale || curLocale
+            locale: nextLocale || curLocale,
+            // Always include a prefix when changing locales. Theoretically,
+            // this is only necessary for the case described in #2020. However,
+            // the full detection is rather expensive, and this behavior is
+            // consistent with the `Link` component. The downside is an
+            // additional redirect for users in other situations. Locale
+            // changes should be rare though, so this might be fine.
+            forcePrefix: nextLocale != null || undefined
           });
 
           const args: [href: string, options?: Options] = [pathname];

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

@@ -33,6 +33,9 @@ function BaseLink(
   const pathname = usePathname() as ReturnType<typeof usePathname> | null;
 
   function onLinkClick(event: MouseEvent<HTMLAnchorElement>) {
+    // Even though we force a prefix when changing locales,
+    // this could be a cache hit of the client-side router,
+    // therefore we sync the cookie to ensure it's up to date.
     syncLocaleCookie(localeCookie, pathname, curLocale, locale);
     if (onClick) onClick(event);
   }