Custom 404 pages in localized sites

[Sporiff]

Astro Info

Astro                    v4.15.11
Node                     v22.9.0
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             auto-import
                         @astrojs/react
                         astro-expressive-code
                         @astrojs/mdx
                         @astrojs/tailwind
                         @astrojs/sitemap
                         @astrojs/markdoc

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

I'm using Astro's i18n options to create a localized site in 4 languages: en, ja, zh, ko. A hard requirement for my use case is that we use the prefixDefaultLocale: true setting to ensure that the default locale (en) always appears in the path just like the others.

One thing I need is the ability to create a custom 404 page that gives users instructions on what to do next when they reach a page that doesn't exist. Before I updated to the multi-folder structure, this was achievable by placing a 404.astro in the pages directory. However, this page was not localized properly due to there not being any locale detection present. Since moving to the new folder-based hierarchy, I noticed that the 404.astro doesn't appear in the dist folder after running astro build.

Adding a custom 404.astro to pages/[lang] works if you visit the slug directly (e.g. /en/404), but it doesn't work when actually hitting a 404. I've managed to override this in Vercel by putting in a Vercel redirect that takes any 404 to the /en/404 route then using some client side scripting to push the user to the correct page.

What's the expected result?

I would like to be able to create a custom 404.astro in pages that routes to the custom 404.astro in pages/[lang] so that localized 404 pages may be served. Ideally, it would be good to control this via astro.config.mjs. Having the ability to simply set up locale-based routing to the major pages like index.astro and 404.astro would save a lot of time.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/astro-no-localized-404

Participation

• I am willing to submit a pull request for this issue.

[Southpaw1496]

I don't think this is something that it's possible for Astro to do. Because a 404 could happen on any invalid path, you can't handle it with file-based routing. To get around this, many static hosts simply look for a 404.html page in the root of the site and serve that with all 404 responses, regardless of their path. So, when you make src/pages/404.astro, that renders to /404.html in the output site and is served by the static host.

If you really wanted, you could make a middleware (which will execute on every request) that would check if the slug exists, and serve the correct 404 page based on the user's language. This would, however, require you to use output: server and mean that every request to your site would count as a function invocation on your hosting platform.

[Sporiff]

I don't think this is something that it's possible for Astro to do. Because a 404 could happen on any invalid path, you can't handle it with file-based routing. To get around this, many static hosts simply look for a 404.html page in the root of the site and serve that with all 404 responses, regardless of their path. So, when you make src/pages/404.astro, that renders to /404.html in the output site and is served by the static host.

This is the issue to be solved, I think. I understand that Astro can't know at build time what language someone is going to be using when they hit a nonexistent route (that makes no sense), but currently putting a 404.astro in src/pages when using the prefixDefaultLocale: true setting fails to add the 404 file to the build output.

Of course, you can work around this by adding it to public, but this isn't a great workaround and isn't documented as far as I know.