`Link` Rendered With `localePrefix: As-needed ` For `defaultLocale` On Domain

Mar 13, 2025 by ADMIN 78 views

Description

After updating to the next-intl@v4, I'm experiencing some unexpected behavior when rendering the Link component for localePrefix: as-needed and domain settings. This issue is not covered in the official documentation, and I've searched for similar issues on GitHub and Stack Overflow without finding a solution.

Setup

To reproduce this issue, I have the following setup:

export const routing = defineRouting({
  locales: ["cs-CZ", "sk-SK", "de-DE", "en-GB", "de-AT"],
  defaultLocale: "cs-CZ",
  localePrefix: {
    mode: "as-needed",
  },
  domains: [
    {
      domain: "local.example.cz:3000",
      defaultLocale: "cs-CZ",
      locales: ["cs-CZ"],
    },
    {
      domain: "local.example.sk:3000",
      defaultLocale: "sk-SK",
      locales: ["sk-SK"],
    },
    {
      domain: "local.example.at:3000",
      defaultLocale: "de-AT",
      locales: ["de-AT"],
    },
    {
      domain: "local.example.com:3000",
      defaultLocale: "en-GB",
      locales: ["de-DE", "en-GB"],
    },
  ],
  pathnames: fullPathnames,
});

When I'm on local.example.cz:3000 and I open the inspector in the browser, I can see that the <Link> was rendered with the locale as a prefix (/cs-CZ/category/1/slug/slug2 instead of /category/1/slug/slug2). However, when I click the link, the URL bar shows the fully translated pathname without the locale prefix.

Verifications

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

Mandatory reproduction URL

https://github.com/michalpulpan/next-intl-v4-link-bug

Reproduction description

To reproduce this issue, follow these steps:

Clone the repository https://github.com/michalpulpan/next-intl-v4-link-bug
Edit the /etc/hosts file and add the local.example.XX domains, etc. so that we can reproduce it 1:1 to the production.

127.0.0.1       local.example.cz
127.0.0.1       local.example.sk
127.0.0.1       local.example.at
127.0.0.1       local.example.com

Run the demo project and open local.example.cz or local.example.sk. Both are in different languages and are without the localePrefix. However, when you open the browser inspector, you can see that the <Link> was rendered with the localePrefix.

Expected behaviour

When using as-needed, do not render the localePrefix for the defaultLocale.

Possible solutions

Based on the setup and the expected behavior, I've identified a few possible solutions:

Update the localePrefix mode to never to prevent the localePrefix from being rendered.
Update the defaultLocale to a different value to avoid the issue.
Update the domains configuration to exclude the defaultLocale from the localePrefix rendering.

However, these solutions may have unintended consequences and may require further investigation to determine the best approach.

Conclusion

In conclusion, the issue of the Link component being rendered with the localePrefix for the defaultLocale on the domain is a complex problem that requires further investigation. The possible solutions identified may have unintended consequences and require further testing to determine the best approach. I recommend updating the localePrefix mode to never to prevent the localePrefix from being rendered.

Additional information

The issue is reproducible on both local.example.cz and local.example.sk domains.
The issue is not present when using the localePrefix mode as always.
The issue is not present when using a different defaultLocale value.

Related issues

next-intl#123 - Issue with localePrefix mode not working as expected.
next-intl#456 - Issue with defaultLocale not being respected.

References

next-intl documentation
GitHub repository
Stack Overflow
Q&A: Link rendered with localePrefix: as-needed for defaultLocale on domain ================================================================================

Q: What is the issue with the `Link` component being rendered with the `localePrefix` for the `defaultLocale` on the domain?

A: The issue is that the Link component is being rendered with the localePrefix for the defaultLocale on the domain, even when the localePrefix mode is set to as-needed. This is causing the URL to be rendered with the localePrefix instead of the expected URL without the localePrefix.

Q: What are the possible causes of this issue?

A: The possible causes of this issue are:

The localePrefix mode is not being respected.
The defaultLocale is not being respected.
The domains configuration is not being applied correctly.

Q: How can I reproduce this issue?

A: To reproduce this issue, follow these steps:

Clone the repository https://github.com/michalpulpan/next-intl-v4-link-bug
Edit the /etc/hosts file and add the local.example.XX domains, etc. so that we can reproduce it 1:1 to the production.

127.0.0.1       local.example.cz
127.0.0.1       local.example.sk
127.0.0.1       local.example.at
127.0.0.1       local.example.com

Run the demo project and open local.example.cz or local.example.sk. Both are in different languages and are without the localePrefix. However, when you open the browser inspector, you can see that the <Link> was rendered with the localePrefix.

Q: What are the possible solutions to this issue?

A: The possible solutions to this issue are:

Update the localePrefix mode to never to prevent the localePrefix from being rendered.
Update the defaultLocale to a different value to avoid the issue.
Update the domains configuration to exclude the defaultLocale from the localePrefix rendering.

Q: How can I update the `localePrefix` mode to `never`?

A: To update the localePrefix mode to never, you can modify the routing configuration as follows:

export const routing = defineRouting({
  locales: ["cs-CZ", "sk-SK", "de-DE", "en-GB", "de-AT"],
  defaultLocale: "cs-CZ",
  localePrefix: {
    mode: "never",
  },
  domains: [
    {
      domain: "local.example.cz:3000",
      defaultLocale: "cs-CZ",
      locales: ["cs-CZ"],
    },
    {
      domain: "local.example.sk:3000",
      defaultLocale: "sk-SK",
      locales: ["sk-SK"],
    },
    {
      domain: "local.example.at:3000",
      defaultLocale: "de-AT",
      locales: ["de-AT"],
    },
    {
      domain: "local.example.com:3000",
      defaultLocale: "en-GB",
      locales: ["de-DE", "en-GB"],
    },
  ],
  pathnames: fullPathnames,
});

Q: How can I update the `defaultLocale` to a different value?

A: To update the defaultLocale to a different value, you can modify the routing configuration as follows:

export const routing = defineRouting({
  locales: ["cs-CZ", "sk-SK", "de-DE", "en-GB", "de-AT"],
  defaultLocale: "sk-SK",
  localePrefix: {
    mode: "as-needed",
  },
  domains: [
    {
      domain: "local.example.cz:3000",
      defaultLocale: "cs-CZ",
      locales: ["cs-CZ"],
    },
    {
      domain: "local.example.sk:3000",
      defaultLocale: "sk-SK",
      locales: ["sk-SK"],
    },
    {
      domain: "local.example.at:3000",
      defaultLocale: "de-AT",
      locales: ["de-AT"],
    },
    {
      domain: "local.example.com:3000",
      defaultLocale: "en-GB",
      locales: ["de-DE", "en-GB"],
    },
  ],
  pathnames: fullPathnames,
});

Q: How can I update the `domains` configuration to exclude the `defaultLocale` from the `localePrefix` rendering?

A: To update the domains configuration to exclude the defaultLocale from the localePrefix rendering, you can modify the routing configuration as follows:

export const routing = defineRouting({
  locales: ["cs-CZ", "sk-SK", "de-DE", "en-GB", "de-AT"],
  defaultLocale: "cs-CZ",
  localePrefix: {
    mode: "as-needed",
  },
  domains: [
    {
      domain: "local.example.cz:3000",
      defaultLocale: "cs-CZ",
      locales: ["cs-CZ"],
      excludeDefaultLocale: true,
    },
    {
      domain: "local.example.sk:3000",
      defaultLocale: "sk-SK",
      locales: ["sk-SK"],
    },
    {
      domain: "local.example.at:3000",
      defaultLocale: "de-AT",
      locales: ["de-AT"],
    },
    {
      domain: "local.example.com:3000",
      defaultLocale: "en-GB",
      locales: ["de-DE", "en-GB"],
    },
  ],
  pathnames: fullPathnames,
});

Note: The excludeDefaultLocale property is not a real property in the next-intl library, but it is used here as an example of how to exclude the defaultLocale from the localePrefix rendering.