Path Param Encoding doesn't respect "/" in params

[SteffenAuer]

Description

In v4.2.0, a feature was introduced to encode the pathname before sending it over to Next.js routing. However, if a dynamic path param contains a /, it is treated as a path separator instead of a value of the param and not encoded in the URL, leading to a different page. If the param value is encoded before passing to next-intl, the resulting URL contains double encoded characters.

Verifications

• I've verified that the problem I'm experiencing isn't covered in the docs.
• I've searched for similar, existing issues on GitHub and Stack Overflow.
• I've compared my app to a working example to look for differences.

Mandatory reproduction URL

https://github.com/SteffenAuer/next-intl-encoding-issue

Reproduction description

Steps to reproduce:

1. Open reproduction
2. There's three links. All attempt to point to /en/test/[param] with the param value being Foo / Bar %
   1. No encoding on my end, passing that param value above straight to next-intl Link
   2. Encoded the param value before passing it to next-intl Link
   3. Regular a tag with manually built pathname. This is the expected value
3. Notice the issue: The first link leads to a 404, the second and third link lead to the correct page. However, the second link contains double encoded values (e.g. instead of %2F for a /, it has %252F: The % from the encoded / is encoded again)

Expected behaviour

The expected href is the one of the third link on the reproduction page. There should be no encoding necessary before passing the param values to next-intl.
I believe this is the issue:

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

Lines 209 to 212 in 081d952

	return pathname
	.split('/')
	.map((segment) => encodeURIComponent(segment))
	.join('/');

. Instead of encoding the entire pathname split at /, the params should be encoded individually before being applied to the template. It should not assume that the param values don't contain / characters.

[amannn]

the second and third link lead to the correct page

Not sure if I'm doing something wrong, but the third link with href="/en/test/Foo%20%2F%20Bar%20%25" leads to a 400 for me while the second one works:

Kapture.2025-09-10.at.14.05.00.mp4

[SteffenAuer]

the second and third link lead to the correct page

Not sure if I'm doing something wrong, but the third link with href="/en/test/Foo%20%2F%20Bar%20%25" leads to a 400 for me while the second one works:
Kapture.2025-09-10.at.14.05.00.mp4

Sorry about that. This seems to be a separate (I assume nextjs) issue. Apparently, if there's an encoded % in the url (i.e. %25), it wrongly throws a 400.
I've removed the % in the reproduction repo now, since it is not related nor relevant to this issue. If you could try again with the latest commit 🙏

[amannn]

Got it, thanks! So I took another look at this, and I think what next-intl should do here is avoid an additional encoding pass if you already provide encoded params.

A param of 'Foo / Bar ' is really a bit ambiguous and asks for trouble IMO. While the spaces (' ') do require encoding, the slash (/) actually doesn't, since it's a valid part of typical pathnames. Potentially, you shouldn't pass it as an unencoded character in the first place.

However, previously you couldn't encode it, because next-intl would add an additional encoding pass on top.

With #2017, I've adapted this to avoid double-encoding of already encoded params.

So in your case, you'd be able to do something like this:

<Link
  href={{
    pathname: '/test/[param]',
    params: {
      param: encodeURIComponent('Foo / Bar ')
    }
  }}
>

Does that sound right to you?

[SteffenAuer]

I think double encoding should certainly be avoided. I'm wondering though, why not apply this approach to the params individually, instead of to the entire pathname? So, why not encode the params before applying the pathname template?

[amannn]

I think double encoding should certainly be avoided.

I agree, I'll merge #2017 now in any case as it's already an improvement.

why not apply this approach to the params individually

I've been thinking a bit more about this and it's certainly an interesting question.

My thoughts are:

• URLs must be ASII-only. next-intl already ensures this, so e.g. if you use pathnames with umlauts, Chinese characters, emojis etc.—then all relevant encoding is done for you.
• There are certain characters like /, ?, # that are valid in pathnames, but have a dedicated function (separating pathname segments, indicating search params, hash fragments, …).

So I think the question comes down to if next-intl should encode such characters in params. I think I see your point in that it would be nice for this use case if it did, but I wonder if it could have unexpected consequences.

E.g. something like this:

import Link from 'next/link';

<Link href="/en/test/Foo / Bar" />

… will also use the pathname as-is. It's arguably a bit different though since Next.js simply accepts a string-based href and not params individually.

Probably a closer example are path params in Tanstack Router. Notably, they use encodeURIComponent on all params by default, so pretty much the behavior you're looking for I think.

However, interestingly, they had to follow-up with pathParamsAllowedCharacters to allow characters like @ which might be unnecessarily encoded.

I don't really want to get into the territory of handling such configuration, so I think leaving this decision in userland might be more flexible. There, you can decide if you just want to use encodeURIComponent, or something more sophisticated like slugify.

Also, my impression is that the kind of params developers usually provide to next-intl are already rather slugs that can be directly used and don't rely on further encoding—so we can avoid unnecessary work here.

So tldr; I think this gave me clarity that for the time being I'd not encode params. So in your case, I'd suggest to use encodeURIComponent yourself—hope that makes sense!

[SteffenAuer]

This all makes total sense. Thank you for the effort and detailed explanation!