Per-domain `localePrefix` override

[frankmatheron]

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

Currently, when using domain-based routing with next-intl, all domains must follow the same localePrefix mode (e.g., always, never, or as-needed). This creates limitations when different domains have different requirements for locale prefix behavior.

For example, you might want:

• A single-locale domain (e.g., us.example.com) to never show locale prefixes
• A multi-locale domain (e.g., ca.example.com) to always show locale prefixes for clarity

The current workaround requires building the app separately for each domain with different configurations, which is not ideal for deployment and maintenance.

Describe the solution you'd like

Allow each domain in the domains configuration to optionally specify its own localePrefix mode that overrides the global setting:

export const routing = defineRouting({
  locales: ['en-US', 'en-CA', 'fr-CA'],
  defaultLocale: 'en-US',
  domains: [
    {
      domain: 'us.example.com',
      defaultLocale: 'en-US',
      locales: ['en-US'],
      localePrefix: 'never' // Override: no prefix on this domain
    },
    {
      domain: 'ca.example.com',
      defaultLocale: 'en-CA',
      locales: ['en-CA', 'fr-CA'],
      localePrefix: 'always' // Override: always show prefix on this domain
    }
  ],
  localePrefix: 'as-needed' // Global default
});

Describe alternatives you've considered

I considered using separate builds per domain (as described in the docs), but I would prefer not to because: Increases build time, deployment complexity, and maintenance burden. Also increases our runtime costs.

[amannn]

Thanks for the feature request and for your PR!

This was historically a bit hard to achieve, but with stricter config for domains in next-intl@4 the situation might have changed a bit. I'll have to reevaluate this in detail when time permits to research if this has any hidden tradeoffs. It's not only about the navigation APIs btw., but also the middleware. In any case, we need solid e2e coverage (currently done in example-app-router-playground)—the unit tests hide some relevant details.

The other aspect is that the middleware is somewhat in a feature freeze currently, related to #1362. Maybe at some point a bigger refactor is necessary.

For the time being, the docs mention this limitation and also suggest a workaround.

[frankmatheron]

Yes indeed, the stricter config for domains made this easier to achieve.

As for the workaround, I considered it, but I think adds to much infrastructure overhead in our case. As I understand it, the workaround entails building and hosting separate instances of the application for each domain. In our case the impact of this is worsened as we are implementing a complex multi-zone solution: we have multiple NextJS apps under each domain, and the workaround would not result in 2 instances instead of 1, but 10 instead of 5 (or more).
Nevertheless, the mention of the workaround is appreciated, and it would have been a good solution in any other case.

Should I add e2e coverage for this in the PR? Do you have a preferred way that is done?

[frankmatheron]

I have pushed some changes in the PR to support the domain localePrefix override in the middleware too. However, you mention a feature freeze on the middleware?

[amannn]

Got it, I understand!

I'm just a bit short on time currently since I'm very focused on #1 (which is currently the most-requested feature request for next-intl) and I also have some priorities besides next-intl.

I'm also currently lacking a bit of context for this feature. It used to be hard to achieve in the past, but as mentioned above, since next-intl@4, it might be doable. But this would require a bit of research into edge cases and possibly implied tradeoffs.

Glancing over the PR you opened, I can see that you clearly put in the effort to do this cleanly.

So how about this:

1. Some e2e testing similar to https://github.com/amannn/next-intl/blob/main/examples/example-app-router-playground/tests/domains.spec.ts would be very important to verify the middleware and navigation APIs work as expected.
2. Once all tests pass, I'll put some time aside for a review.
3. If all looks good, I can publish a prerelease with the feature for you to test drive in your app.
4. If we have confidence that this works well, we can aim to release it in stable.

Does that sound good to you?

Somewhat related, you can of course always implement your own middleware and navigation APIs while keeping the rest of next-intl. But depending on which routing features you need, this might require more effort (e.g. pathnames is a tricky one).

[frankmatheron]

I completely understand, time is a limited resource 😄! I'll add the e2e tests for this, and then we take it from there.

Thank you!