Feature Request: RoutingConfig for Locale Cookie Sync Control

[AirboZH]

Is your feature request related to a problem? Please describe.

I've designed a multilingual switching logic(Prefix-based routing) that prioritizes user choice over automatic redirection. Inspired by Notion's approach, this design offers a potentially mainstream solution for language preference handling on websites.

Flowchart below:

In this flow, the Locale Cookie is only modified when the user explicitly confirms, either by clicking language switch prompts or using the language selector. When a Locale Cookie exists, accessing pages with a language differing from the Locale Cookie language will result in a redirect to the language set in the Locale Cookie.

The language priority is as follows:

1. Locale Cookie
2. Browser Language Preference (used only for prompting language switching)
3. Default Language

Currently, next-intl doesn't perfectly meet my needs.

A key point is that next-intl currently prioritizes path language over the Locale Cookie.

This means that even with localeDetection: false and localePrefix: "as-needed", visiting / will set the language to the default language.

Describe the solution you'd like

I hope next-intl could offer a RoutingConfig option to disable Locale Cookie setting based on path. It would be best if next-intl exported a setLocaleCookie method. That allow me to achieve the desired behavior – implementing my own Locale Cookie logic or using setLocaleCookie method.

Describe alternatives you've considered

It might be helpful to add a RoutingConfig configuration check before the syncCookie call:

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

Lines 311 to 318 in d6c0e91

	}
	}
	syncCookie(request, response, locale, resolvedRouting, domain);
	if (
	!hasRedirected &&
	resolvedRouting.localePrefix.mode !== 'never' &&

Or, perhaps include a RoutingConfig configuration check before "Prio 1: Use route prefix" to allow skipping this priority step altogether.

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

Lines 101 to 108 in d6c0e91

	// Prio 1: Use route prefix
	if (pathname) {
	locale = getPathnameMatch(
	pathname,
	routing.locales,
	routing.localePrefix
	)?.locale;
	}

In fact, I've noticed a similar issue #735 in the repository. However, I believe my request might differ from that one, hence this new issue.

I'd be grateful for your feedback/suggestions, thank you.

next-intl is a very efficient tool. If it's helpful, I would be happy to submit a PR.

[amannn]

Hey, thanks for carefully writing down your thoughts!

Inspired by Notion's approach

Interesting, it's the first time I notice that a website would ignore the path in favor of a cookie value.

Other websites like e.g. microsoft.com choose a different approach, where the path always wins and missing locales in the path are filled in based on a cookie value. That's the approach that next-intl currently provides too out-of-the-box.

Redirecting users to another language is something that needs to be done very conservatively. The Google Search Central docs on multiregional websites go as far as:

Avoid automatically redirecting users from one language version of a site to a different language version of a site. For example, don't redirect based on what you think the user's language may be. These redirections could prevent users (and search engines) from viewing all the versions of your site.

next-intl currently has some redirects in place, but we try to be conservative and try to not redirect more often than needed. E.g. the alternate links that are returned as response headers point to pathnames that can be visited to switch the language—it may not be ideal if those links would redirect back.

I know with the localePrefix: 'as-needed' strategy this is already a bit stretched, but at least users can disable redirects with localeDetection: false.

More redirects are currently not something I'm looking for. I'd argue it's also not so common for users to end up on pathnames with different locale prefixes—if you use the routing APIs from next-intl, then users should navigate within a particular locale.

That being said, you can always compose the middleware and add custom redirects on top.

I made a note of this issue in #1362 though, there are some cases where I'd wish the middleware would work a bit better. I'm not sure yet if it's a good idea to introduce more flexibility since this can also pose potential footguns, or if providing your own custom middleware is something that should be documented (that would require rootParams to ship in Next.js).

As a side note, the pattern of comparing the matched language on the client side with e.g. navigator.language is a reasonable idea—many websites use this pattern to display a hint that allows the user to easily switch the language. I think this pattern is generally preferable in comparison to automatically redirecting.

[amannn]

As a small follow-up: Navigating to another locale prefix is the mechanism that's used for updating a potential locale cookie as part of locale switchers that use Link. This is designed as a reliable mechanism that works even before/without hydration.

I'd say the middleware and navigation APIs that are configured via defineRouting are really designed to work in a compatible way. With the current feature set, we can provide a guarantee that these work well together.

If e.g. the middleware would prefer cookie values over locale prefixes, this would break an assumption of Link to be potentially used in locale switchers. That's quite the reason why I'm hesitant to introduce routing options that could break such features.

[AirboZH]

Thank you so much for your patient and quick response! I really appreciate it.

I completely agree with the point from the Google Search Central documentation about avoiding redirects based on assumed user language. You're right to be conservative with redirects.

Regarding my mention of Notion, I admire their approach specifically because it allows users to access the root path, '/', directly without any language prefix like /en or /zh. My main goal was to achieve a similar clean domain landing page.

I realized that using localeDetection: false and localePrefix: "as-needed" in combination with Link actually perfectly addresses my needs. I'm going to proceed with this approach.

Thank you for sharing your insights on i18n. Thinking through this and understanding your perspective has been very educational for me.

You are definitely a top-tier open-source author! Keep up the great work! 🚀

[amannn]

Hey, thank you so much for your kind words—really happy to hear if this was helpful!

You should definitely share the site you're working on, I'm always curious! 🙂

[AirboZH]

Yeah, it's this note-taking thing we're building with AI features, and we're starting out by focusing on international students. next-intl has been amazing for setting up the multi-language stuff right from the get-go. It's a key feature for us straight away!

This App is still in development, but we just rolled out the official website.

https://suminote.com/

[amannn]

That looks like an incredibly cool and useful project! I'm a university teacher myself, so I'm naturally curious about this topic 🤓

I'll definitely follow along!