6 Pitfalls of Building a Multilingual Site with Next.js 15: From Query Strings to URL Paths

Building a multilingual website with Next.js 15 can be challenging, with several pitfalls to be aware of. This story covers the author's experience of tackling these issues while creating a 150+ tool website on Cloudflare Pages.

The first pitfall, Pitfall 1: Nested Root Layout, occurs when switching languages on a page leads to a crash or blank screen. The root cause is that Next.js 15 App Router renders both app/layout.tsx and app/[locale]/layout.tsx, which can cause double HTML rendering and hydration issues. The solution is to return only children in the root layout file.

Pitfall 2: redirect() Doesn't Work with Static Export is another issue faced by the author. The problem arises when redirecting the root path / to /en/ or /zh-CN/ based on the user's browser language, but the redirect() function does not work in static export mode. The fix involves using client-side JavaScript to handle the redirection, with a noscript fallback to ensure compatibility with non-JS environments.

Finally, Pitfall 3: Passing Locale to generateMetadata is a mistake that causes all tool page titles to appear in English, regardless of the visitor's language preference. The root cause is that generateMetadata() receives params as an async promise, which can lead to undefined or error values. To fix this, the author uses the new Next.js 15 way of passing params, which resolves the issue and ensures the correct locale-specific metadata is displayed.