Skip to content

feat(404): show the not-found page in the reader's language - #2583

Open
NopeCharon wants to merge 1 commit into
expressjs:mainfrom
NopeCharon:feat/localized-404-page
Open

NopeCharon wants to merge 1 commit into
expressjs:mainfrom
NopeCharon:feat/localized-404-page

Conversation

@NopeCharon

Copy link
Copy Markdown
Contributor

The host serves one 404.html for every missing URL, whatever its language, and that page is hardcoded in English. Crowdin already translates the error404 UI strings into every supported language, but nothing uses them. A reader who follows a broken link on /de/… or /ja/… gets an English page. Its Go to Home button points to /en, so it also takes them out of their language. The second button is labelled "Raise a issue".

This builds the 404 page from the error404 strings:

  • The page is still rendered in English. A small inline script runs right after the content and reads the language prefix of the requested URL. For any supported language other than English, it swaps in that language's strings before the first paint. It also updates <html lang>/dir and the document title, and points Go to Home at that language's homepage (e.g. /de/).
  • English, unprefixed, and removed-locale URLs (e.g. /ru/…) keep the English page. Its home link now goes to /, the canonical English homepage, instead of /en.
  • Adds an error404.reportIssue string ("Report an issue") so the second button can be translated through Crowdin like the rest of the page. Until it is translated, it falls back to English.

Only the 404 page content is localized. The surrounding header, sidebar and footer are unchanged.

Validation

  • Added tests/e2e/not-found.spec.ts. It covers the English fallbacks (/en/…, unprefixed, removed locale) and all nine translated languages, checking the 404 status, lang, title, heading, message and home link. It passes in Chromium, Firefox and WebKit against npm run preview of a production build, and in Chromium and Firefox against npm run dev. All 12 cases per browser fail on main.
  • npm run check, npm run test:unit and npm run build pass.

The site is deployed as static files, so the host serves the same
`404.html` for every missing URL, whatever its language. That page was
hardcoded in English, even though Crowdin already translates the
`error404` strings into every supported language. The strings were
never used. The "Go to Home" button also pointed to `/en`, which drops
readers of translated docs back into English, and the second button
was labelled "Raise a issue".

Build the 404 page from the `error404` UI strings. It still renders in
English. A small inline script that runs right after the content reads
the language prefix of the requested URL (e.g. `/de/guide/missing`).
For a supported language other than English, it swaps in that
language's strings before the first paint. It also updates the `lang`
and `dir` attributes on `<html>` and the document title, and points
"Go to Home" at that language's homepage. English, unprefixed, and
removed-locale URLs keep the English page, which now links to `/`, the
canonical English homepage.

Add an `error404.reportIssue` string ("Report an issue") for the second
button so it can be translated through Crowdin like the rest of the
page. Until it is translated, it falls back to English.

Add Playwright tests covering the English fallbacks and every
translated language.

Signed-off-by: NopeCharon <115794254+NopeCharon@users.noreply.github.com>
@NopeCharon
NopeCharon requested a review from a team as a code owner November 13, 2026 05:18
@netlify

netlify Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for expressjscom-preview ready!

Name Link
🔨 Latest commit 862ed32
🔍 Latest deploy log https://app.netlify.com/projects/expressjscom-preview/deploys/6af69d964552c4b5a47d9e48
😎 Deploy Preview https://deploy-preview-2583--expressjscom-preview.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 98 (🟢 up 1 from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: 80 (no change from production)
View the detailed breakdown and full score reports
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant