Less aggressive Behavior in Locale Handling

[ScreamZ]

Hi, first I would like to say that I'm a huge fan of all this work!

This post is my first rock on a series of thoughts about the current state of the library. I have a small Trello with things I've detected and I would like to report, here is one, that I encounter very often.

Hope you'll like the suggestion and not die suddenly when you'll see the length of the post 🤣 I'll try to be concise.

Important

First I would like to remember that I'm using a highly hybrid approach for the localized path and not the « full localized one ».

• I have sections of my app that are localized.
• Some that are not, like Webhooks endpoints for Stripe, and various things like CMS Sync webhooks.
• Or even worse my custom bridge for NextAuth that is the only way I found to make it work in AuthJS 5 as for now.

Note

I'm aware that the next-intl documentation invites us not to use this pattern as we already discussed it in another thread if I'm not wrong. It rather suggests to split the application into two apps or starting localizing API routes. But there are some edges cases like for Next auth.

When we chose that path, it's advised to have 0 code relying on next-intl automated function that gets locale, like getLocale without args, or Links.

I'm trying my best when not in the internationalized section to not use those APIs, but sometimes as I'm using nested components or functions that rely on that elsewhere (even in RSC), I get shot silently and I discover my issues when they are in production (and a lot of users have cases that I didn't found or tested. People ends-up in Not Found page, and it's hard to track. I just spent 3 hours making a git diff to detect that 10 minutes ago.

I ended up making a kind of mimic of what the middleware does for those sections of the app that aren't in the i18n router context. But less aggressive

/**
 * Ensure locale or fallback if not provided.
 * A function to use most of time out of next-intl router context, as any function like `getLocale` will trigger a `notFound` invocation and cause unexpected behavior.
 */
export function validateLocaleOrFallback(locale?: string): AvailableLocales {
  if (!locale || !AvailableLocales.includes(locale as AvailableLocales)) {
    const cookiesList = cookies();

    locale = cookiesList.get("NEXT_LOCALE")?.value;

    if (locale) return locale as AvailableLocales;

    const headersList = headers();

    // Can be Accept-Language: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 on safari worst case scenario
    locale = headersList.get("accept-language")?.split(",")[0]; // fr-CH, fr;q=0.9 => fr-CH
    locale = locale?.split("-")[0].toLocaleLowerCase(); // fr-CH => fr

    // Check if exists and valid (also stripe *)
    if (locale && AvailableLocales.includes(locale as AvailableLocales)) return locale as AvailableLocales;

    return AvailableLocales[0]; // Final fallback
  }

  return locale as AvailableLocales;
}

People might say:

💡 You could rather use the middleware on every path, you wouldn't have the issue!

I would like to, but the issue is that the middleware will automatically try to re-route if the path does not match a localized path. Which is useful most of the time, but damn annoying in my case.

Here are my thoughts about the problem and possible solutions I have, but I need some help and design! As I might not be aware of all the side effects this could have. You're the expect here @amannn after all! And I would be pleased to learn from you things ;)

Problem: Aggressive NotFound Redirection in Locale Middleware

When we call getLocale (or other APIs that rely on locale), if the middleware hasn’t been executed, a notFound() is triggered immediately.

This behavior feels a bit too aggressive to me, especially in cases where we would prefer to handle locale resolution more flexibly.

If we take the source of the problem, we need to execute the middleware to guess the locale, as I do with my validateLocaleOrFallback function above, except that in that one, I don't have access to the path name.

If we look at the documentation without i18n routing we see a cool thing:

next-intl creates a request-scoped configuration object, which you can use to provide messages and other options based on the user's locale to Server Components.

// src/i18n/request.ts
import {getRequestConfig} from 'next-intl/server';
 
export default getRequestConfig(async () => {
  // Provide a static locale, fetch a user setting,
  // read from `cookies()`, `headers()`, etc.
  const locale = 'en';

 return {
   locale,
   messages: (await import(`../../messages/${locale}.json`)).default
 };
});

❗️However the issue is:

Currently, there’s no way to use getRequestContext to determine the final locale and return a different one. The locale middleware acts strictly and enforces its logic without room for adjustment.

If you use

// This 'locale' is supposed to be the one provided by the next-intl middleware
export default getRequestConfig(async ({ locale }) => {

 const finaleLocale = "Mandalorian" // I DONT CARE about if the middleware ran or not. Maybe I'm in a SPA not exposed publicly. Or maybe I'm just running my own code to guess the locale as I don't trust you! Or I'm just trolling for May 4th and return a star wars language not matter what and kill my SEO (May the 4th be with you)

  // Validate that the incoming `locale` parameter is valid
  if (!AvailableLocales.includes(locale as ArrayValues<typeof AvailableLocales>)) {
    notFound(); // I HANDLE notFound() myself, and I don't need getLocale or any to do it.
  }

  return {
    locale:  finaleLocale
    messages: (await import(`./messages/${finaleLocale}.json`)).default,
  };
});

This doesn't work. Because you cannot read the locale and return another with the current setup. Why is this a restriction? I understand this is a guard. But with proper documentation and naming, this could be easy to not fail.

Suggested Solution

What I propose is a more flexible approach IMO where:

• Every time a server-side call is made for something that relies on locale or whatever.
• We call getRequestContext to allow the user to determine the final locale.
  • if the middleware ran as part of the request cycle, and was able to determine somehow the locale.
  • We pass it as an argument to getRequestContext, (we can even pass what matched: route/cookie/accept-Language header/fallback)
• The middleware acts more like a helper that pre-fills the locale but doesn’t enforce it strictly.
• Therefore the user can use this information, or just say « No I don't care ».
• As this argument is optional, there is no constraint, you can model all use cases already existing.

For client-side calls, with the context provider, I guess we have the same logic. As it's prefilled with data coming from getRequestContext

Another workaround I found is wrapping getLocale() with my custom code that try/catch around and fallback. But this still display the warning in the logs, its kind of hacky and doesn't solve the issue for API like the localized Links.

Unable to find next-intl locale because the middleware didn't run on this request. See https://next-intl-docs.vercel.app/docs/routing/middleware#unable-to-find-locale. The notFound() function will be called as a result.

Benefits

• Flexibility: Developers will have more control over locale handling, with the ability to return different locales based on whatever they want. The middleware is still optional but even more useful because It only does one thing: guessing the locale not redirecting without inviting us to do so.
• Less Aggressive: Instead of automatically redirecting with a notFound(), the system allows for fallback or custom handling logic, making the application more user-friendly and adaptable to different use cases. We can even redirect to one page that invite you to choose the locale, and not to the notFound page. Which is a lovely feature not possible yet.

Current Limitation

• As it stands, reading the locale from getRequestContext and returning a different one is not allowed, which limits the customization potential for developers.
• The middleware is too aggressive, and does too many things by default. We should provide an alternative and handle the user configuring it per request in getRequestContext and why not give helpers to help redirecting?

Conclusion

By relaxing the restrictions around locale handling and letting the middleware serve as a helper rather than an enforcer, we can make the system both more flexible and developer-friendly.

Would love to hear feedback or ideas on this!

Andréas

[ScreamZ]

Have looked at other solution a bit too, while next-intl is my go-for for various reasons, I like the way some handle our issue:
https://next-international.vercel.app/docs/app-middleware-configuration#override-the-users-locale-resolution

[amannn]

This is btw. slightly different, it'd be equivalent to providing a new option on the middleware. next-international also uses the approach where a header is passed from the middleware to the [locale] segment.

What we want here though is initializing a locale for usage in server-only code.

[amannn]

Hey Andréas,

thank you so, so much for the thoughtful post! I luckily didn't die suddenly while looking at it, so all good! 😄 This kind of feedback is immensely helpful—definitely keep it coming in case you have more! ❤️

I think you have a valid point here. The current design for getRequestConfig is based on passing a locale to the user that was negotiated by the middleware. Only at a later point, in next-intl@3.14 the feature was added to return a locale, for cases where no i18n routing is needed.

Reading a locale from the params that are passed to getRequestConfig and returning a different one is currently not supported, because it could indicate an erroneous setup. So far, I also can't think of a use case where a mapping between locales is necessary (esp. since custom prefixes are supported—so you can still map a Mandalorian pathname/locale, but prefixes is the expected API for this).

That being said, I think the story is a different one for initializing the locale in case none was provided by the middleware.

Use cases could be:

1. Route Handlers outside of the [locale] segment
2. A fallback for requests that don't match the middleware

In regard to (1) I'd personally recommend an explicit contract like a search param ?locale= for such a case though.

In regard to (2), this would unlock two cases that have been somewhat tough to support so far:

1. A locale/country selection page at /
2. A global 404 page for requests like /unknown.txt

An example snippet for using the default locale for such cases could look like this:

import {routing} from './routing';

export default getRequestConfig(async ({ locale = routing.defaultLocale }) => {
  // Validate that the incoming `locale` parameter is valid
  if (!routing.locales.includes(locale as any)) notFound();

  return {
    locale,
    // ....
  }
});

As you're rightfully saying, probably not much to ask from a user, while providing a more frictionless experience, and at the same time providing more flexibility.

The error "Unable to find next-intl locale because the middleware didn't run (…)" is currently one of the most annoying ones in next-intl, so if this helps to reduce this error, it'd be a welcome change from my perspective.

The change would involve:

1. The locale param is now typed as optional (and therefore requires a default)

To consider:

1. Should a locale always be returned, even if the user just passes it through? I'm currently thinking yes, because this way we always have a fallback. Otherwise we're in the same position as before, where we have to abort the rendering with a 404.
2. If no locale is available after getRequestConfig has run, we probably still need to abort the render with a call to notFound(), but you'll practically never see this error.
3. Should we error/warn in case a valid locale is passed to getRequestConfig and a different one returned? (i.e. is initialization the only use case we want to support?) This might be helpful theoretically, but practically it's likely not possible, because for the setup without i18n routing, we'd needlessly attempt to read from headers, potentially breaking static rendering.

One drawback that comes to my mind:

1. If the matcher of the user doesn't consider all valid cases (e.g. /users/jane.doe), this could erroneously render with the default locale. Currently, we return an error here, potentially nudging the user towards fixing the error.

I probably need to prototype this to get a deeper understanding about the implications, but from what I can currently tell, this would be a welcome change! 💯

Regarding rollout we'd have to make this a breaking change, since the locale is currently typed as non-nullable. That's at least the case if we reuse the existing param (e.g. ({params: {locale}}) could be an incrementally adoptable alternative), but maybe that's not worth it.

I'm making a note of this in #779!

[amannn]

Side note: The use cases that are currently somewhat hard to achieve (locale/country selection at / and a global 404 page) can currently be realized by passing an explicit locale to getTranslations:

const t = await getTranslations({namespace: 'IndexPage', locale: 'en'});

This value is used as an override that is passed to getRequestConfig and avoids reading from headers entirely.

Note that this is currently only possible via the async getTranslations—not via useTranslations.

An implication for this use case is generally that when Client Components need to be used, you'd have to add a NextIntlClientProvider for this particular page (or in a global root layout).

[amannn]

A first implementation was done in #1383. I think we can introduce this in a non-breaking way in the next minor version while also addressing the change in Next.js 15 where headers() will switch to being async.

One thing I noticed during the implementation: Receiving one "locale" and returning another is in fact useful and also necessary when a pathname that is not matched by the middleware is called and accidentally ends up in the [locale] segment (e.g. /unknown.txt)—see the PR for details.

One thing that's left out for now, but will likely make it into the next major version, is that the locale that is returned by getRequestConfig is still optional. In the future, I'd like to make this mandatory to avoid errors.

[amannn]

@ScreamZ This has been addressed in #1383 and is currently available in next-intl@canary (see #1391).

Let me know if everything works as you'd expect in case you try out the prerelease!

[ScreamZ]

I'll check in the week, thanks for feedback (also will read your full post)

[ScreamZ]

I've started some feedback on #1391