feat: Add localePrefix for navigation APIs for an improved initial render of Link when using localePrefix: never. Also fix edge case in middleware when using localized pathnames for redirects that remove a locale prefix (fixes an infinite loop).

packages/next-intl/package.json

@@ -86,6 +86,7 @@
     "@types/negotiator": "^0.6.1",
     "@types/node": "^17.0.23",
     "@types/react": "18.2.34",
+    "@types/react-dom": "^18.2.17",
     "eslint": "^8.54.0",
     "eslint-config-molindo": "^7.0.0",
     "eslint-plugin-deprecation": "^1.4.1",

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

@@ -1,6 +1,4 @@
-import {AllLocales, Pathnames} from '../shared/types';
-
-type LocalePrefix = 'as-needed' | 'always' | 'never';
+import {AllLocales, LocalePrefix, Pathnames} from '../shared/types';
 
 type RoutingBaseConfig<Locales extends AllLocales> = {
   /** A list of all locales that are supported. */

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

@@ -1,6 +1,11 @@
 import React, {ComponentProps, ReactElement, forwardRef} from 'react';
 import useLocale from '../../react-client/useLocale';
-import {AllLocales, ParametersExceptFirst, Pathnames} from '../../shared/types';
+import {
+  AllLocales,
+  LocalePrefix,
+  ParametersExceptFirst,
+  Pathnames
+} from '../../shared/types';
 import {
   compileLocalizedPathname,
   getRoute,
@@ -16,7 +21,15 @@ import useBaseRouter from './useBaseRouter';
 export default function createLocalizedPathnamesNavigation<
   Locales extends AllLocales,
   PathnamesConfig extends Pathnames<Locales>
->({locales, pathnames}: {locales: Locales; pathnames: PathnamesConfig}) {
+>({
+  localePrefix,
+  locales,
+  pathnames
+}: {
+  locales: Locales;
+  pathnames: PathnamesConfig;
+  localePrefix?: LocalePrefix;
+}) {
   function useTypedLocale(): (typeof locales)[number] {
     const locale = useLocale();
     const isValid = locales.includes(locale as any);
@@ -56,6 +69,7 @@ export default function createLocalizedPathnamesNavigation<
           pathnames
         })}
         locale={locale}
+        localePrefix={localePrefix}
         {...rest}
       />
     );

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

@@ -1,15 +1,33 @@
-import {AllLocales} from '../../shared/types';
+import React, {ComponentProps, ReactElement, forwardRef} from 'react';
+import {AllLocales, LocalePrefix} from '../../shared/types';
 import BaseLink from './BaseLink';
 import baseRedirect from './baseRedirect';
 import useBasePathname from './useBasePathname';
 import useBaseRouter from './useBaseRouter';
 
 export default function createSharedPathnamesNavigation<
   Locales extends AllLocales
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- The value is not used yet, only the type information is important
->(opts: {locales: Locales}) {
+>(opts: {locales: Locales; localePrefix?: LocalePrefix}) {
+  type LinkProps = Omit<
+    ComponentProps<typeof BaseLink<Locales>>,
+    'localePrefix'
+  >;
+  function Link(props: LinkProps, ref: LinkProps['ref']) {
+    return (
+      <BaseLink<Locales>
+        ref={ref}
+        localePrefix={opts.localePrefix}
+        {...props}
+      />
+    );
+  }
+  const LinkWithRef = forwardRef(Link) as (
+    props: LinkProps & {ref?: LinkProps['ref']}
+  ) => ReactElement;
+  (LinkWithRef as any).displayName = 'Link';
+
   return {
-    Link: BaseLink as typeof BaseLink<Locales>,
+    Link: LinkWithRef,
     redirect: baseRedirect,
     usePathname: useBasePathname,
     useRouter: useBaseRouter

packages/next-intl/src/navigation/react-server/createLocalizedPathnamesNavigation.tsx

@@ -1,6 +1,11 @@
 import React, {ComponentProps} from 'react';
 import {getRequestLocale} from '../../server/RequestLocale';
-import {AllLocales, ParametersExceptFirst, Pathnames} from '../../shared/types';
+import {
+  AllLocales,
+  LocalePrefix,
+  ParametersExceptFirst,
+  Pathnames
+} from '../../shared/types';
 import {
   HrefOrHrefWithParams,
   HrefOrUrlObjectWithParams,
@@ -13,7 +18,15 @@ import baseRedirect from './baseRedirect';
 export default function createLocalizedPathnamesNavigation<
   Locales extends AllLocales,
   PathnamesConfig extends Pathnames<Locales>
->({locales, pathnames}: {locales: Locales; pathnames: Pathnames<Locales>}) {
+>({
+  localePrefix,
+  locales,
+  pathnames
+}: {
+  locales: Locales;
+  pathnames: Pathnames<Locales>;
+  localePrefix?: LocalePrefix;
+}) {
   type LinkProps<Pathname extends keyof PathnamesConfig> = Omit<
     ComponentProps<typeof BaseLink>,
     'href' | 'name'
@@ -40,6 +53,7 @@ export default function createLocalizedPathnamesNavigation<
           pathnames
         })}
         locale={locale}
+        localePrefix={localePrefix}
         {...rest}
       />
     );

packages/next-intl/src/navigation/react-server/createSharedPathnamesNavigation.tsx

@@ -1,11 +1,11 @@
-import {AllLocales} from '../../shared/types';
+import React, {ComponentProps} from 'react';
+import {AllLocales, LocalePrefix} from '../../shared/types';
 import BaseLink from './BaseLink';
 import baseRedirect from './baseRedirect';
 
 export default function createSharedPathnamesNavigation<
   Locales extends AllLocales
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- The value is not used yet, only the type information is important
->(opts: {locales: Locales}) {
+>(opts: {locales: Locales; localePrefix?: LocalePrefix}) {
   function notSupported(message: string) {
     return () => {
       throw new Error(
@@ -14,8 +14,12 @@ export default function createSharedPathnamesNavigation<
     };
   }
 
+  function Link(props: ComponentProps<typeof BaseLink<Locales>>) {
+    return <BaseLink<Locales> localePrefix={opts.localePrefix} {...props} />;
+  }
+
   return {
-    Link: BaseLink<Locales>,
+    Link,
     redirect: baseRedirect,
     usePathname: notSupported('usePathname'),
     useRouter: notSupported('useRouter')

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

@@ -11,16 +11,16 @@ type ReadUntil<Path> = Path extends `${infer Match}]${infer Rest}`
 type RemovePrefixes<Key> = Key extends `[...${infer Name}`
   ? Name
   : Key extends `...${infer Name}`
-  ? Name
-  : Key;
+    ? Name
+    : Key;
 
 type StrictParams<Pathname> = Pathname extends `${string}[${string}`
   ? {
       [Key in ReadFrom<Pathname>[number] as RemovePrefixes<Key>]: Key extends `[...${string}`
         ? Array<ParamValue> | undefined
         : Key extends `...${string}`
-        ? Array<ParamValue>
-        : ParamValue;
+          ? Array<ParamValue>
+          : ParamValue;
     }
   : never;
 

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

@@ -13,10 +13,10 @@ type HrefOrHrefWithParamsImpl<Pathname, Other> =
     ? // Optional catch-all
       Pathname | ({pathname: Pathname; params?: StrictParams<Pathname>} & Other)
     : Pathname extends `${string}[${string}`
-    ? // Required catch-all & regular params
-      {pathname: Pathname; params: StrictParams<Pathname>} & Other
-    : // No params
-      Pathname | ({pathname: Pathname} & Other);
+      ? // Required catch-all & regular params
+        {pathname: Pathname; params: StrictParams<Pathname>} & Other
+      : // No params
+        Pathname | ({pathname: Pathname} & Other);
 
 export type HrefOrUrlObjectWithParams<Pathname> = HrefOrHrefWithParamsImpl<
   Pathname,

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

@@ -4,14 +4,16 @@ import NextLink from 'next/link';
 import {usePathname} from 'next/navigation';
 import React, {ComponentProps, forwardRef, useEffect, useState} from 'react';
 import useLocale from '../react-client/useLocale';
+import {LocalePrefix} from './types';
 import {isLocalHref, localizeHref, prefixHref} from './utils';
 
 type Props = Omit<ComponentProps<typeof NextLink>, 'locale'> & {
   locale: string;
+  localePrefix?: LocalePrefix;
 };
 
 function BaseLinkWithLocale(
-  {href, locale, prefetch, ...rest}: Props,
+  {href, locale, localePrefix, prefetch, ...rest}: Props,
   ref: Props['ref']
 ) {
   // The types aren't entirely correct here. Outside of Next.js
@@ -22,15 +24,17 @@ function BaseLinkWithLocale(
   const isChangingLocale = locale !== defaultLocale;
 
   const [localizedHref, setLocalizedHref] = useState<typeof href>(() =>
-    isLocalHref(href) && locale
-      ? // Potentially the href shouldn't be prefixed, but to determine this we
+    isLocalHref(href) && (localePrefix !== 'never' || isChangingLocale)
+      ? // For the `localePrefix: 'as-necessary' strategy, the href shouldn't
+        // be prefixed if the locale is the default locale. To termine this, we
         // need a) the default locale and b) the information if we use prefixed
-        // routing. During the server side render (both in RSC as well as SSR),
-        // we don't have this information. Therefore we always prefix the href
-        // since this will always result in a valid URL, even if it might cause
-        // a redirect. This is better than pointing to a non-localized href
-        // during the server render, which would potentially be wrong. The final
-        // href is determined in the effect below.
+        // routing. The default locale can vary by domain, therefore during the
+        // RSC as well as the SSR render, we can't determine the default locale
+        // statically. Therefore we always prefix the href since this will
+        // always result in a valid URL, even if it might cause a redirect. This
+        // is better than pointing to a non-localized href during the server
+        // render, which would potentially be wrong. The final href is
+        // determined in the effect below.
         prefixHref(href, locale)
       : href
   );

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

@@ -1,5 +1,7 @@
 export type AllLocales = ReadonlyArray<string>;
 
+export type LocalePrefix = 'as-needed' | 'always' | 'never';
+
 export type Pathnames<Locales extends AllLocales> = Record<
   string,
   {[Key in Locales[number]]: string} | string