fix!: Return x-default alternate link also for sub pages when using localePrefix: 'always' and update middleware matcher suggestion in docs

[amannn]

Previously, we suggested a middleware matcher that looked like this:

// middleware.ts

export const config = {
  // Match only internationalized pathnames
  matcher: ['/', '/(de|en)/:path*']
};

Even though the hardcoded locales need to be updated when new locales are added, this was suggested in light of providing an error-free getting started experience.

However, based on the apps I've seen over time, it seems like this choice was unpopular and users typically go for a matcher that looks like this:

export const config = {
  // Match all pathnames except for
  // - … if they start with `/api`, `/_next` or `/_vercel`
  // - … the ones containing a dot (e.g. `favicon.ico`)
  matcher: '/((?!api|_next|_vercel|.*\\..*).*)'
};

While this avoids hardcoding locales, it requires extra care to match pathnames that contain a dot (e.g. /users/jane.doe).

To align better with user expectations, we now suggest the negative lookahead in the getting started docs and point out the case with pathnames containing dots. As an extra benefit, it makes it significantly easier to switch between routing strategies and add custom prefixes.

With the new matcher in place, the middleware now also returns an x-default alternate link for non-root pathnames (previously only one for / was returned when using localePrefix: 'always'). Due to this, please update your middleware matcher as shown in the getting started docs if you're using alternate links.

Related discussions:

• Matcher string in the docs is buggy #1136
• docs: Fix suggested middleware matcher regex #505
• Faulty regular expression in middleware causes valid URLs to not work #504

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
next-intl-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 17, 2025 4:40pm
next-intl-example-app-router	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 17, 2025 4:40pm
next-intl-example-app-router-without-i18n-routing	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 17, 2025 4:40pm