docs: Improve 404 docs [skip ci]

amannn · Aug 29, 2023 · 7e5ebd1 · 7e5ebd1 · vercel · Aug 29, 2023
1 parent 6efaafc
commit 7e5ebd1
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 6 deletions.
diff --git a/docs/pages/docs/environments/error-files.mdx b/docs/pages/docs/environments/error-files.mdx
@@ -17,7 +17,7 @@ This page provides practical guides for these cases.
 
 ## `not-found.js`
 
-Next.js renders the closest `not-found` page when a route segment calls the [`notFound` function](https://nextjs.org/docs/app/api-reference/functions/not-found). Since the `[locale]` segment is used to localize your app, the `not-found` page needs to be located within this route segment too.
+Next.js renders the closest `not-found` page when a route segment calls the [`notFound` function](https://nextjs.org/docs/app/api-reference/functions/not-found). We can use this mechanism to provide a localized 404 page by adding a `not-found` file within the `[locale]` folder.
 
 ```tsx filename="app/[locale]/not-found.tsx"
 import {useTranslations} from 'next-intl';
@@ -28,7 +28,7 @@ export default function NotFoundPage() {
 }
 ```
 
-Note however, that Next.js will only render this page when the `notFound` function is called from within a route, not for all unknown routes in general.
+Note however that Next.js will only render this page when the `notFound` function is called from within a route, not for all unknown routes in general.
 
 ### Catching unknown routes
 
@@ -46,7 +46,9 @@ After this change, all requests that are matched within the `[locale]` segment w
 
 ### Catching non-localized requests
 
-When the user requests a route that is not matched by [the `next-intl` middleware](/docs/routing/middleware) (depending on your `matcher` config), there's no locale associated with the request (e.g. `/unknown.txt`). You can add a root `not-found` page to handle these cases too.
+When the user requests a route that is not matched by [the `next-intl` middleware](/docs/routing/middleware), there's no locale associated with the request (depending on your `matcher` config, e.g. `/unknown.txt` might not be matched).
+
+You can add a root `not-found` page to handle these cases too.
 
 ```tsx filename="app/not-found.tsx"
 'use client';
@@ -68,7 +70,39 @@ export default function NotFound() {
 }
 ```
 
-Note that a root layout file is required in this case, even if [it's just passing `children` through](https://github.com/amannn/next-intl/blob/main/examples/example-next-13/src/app/layout.tsx).
+Note that the presence of `app/not-found.tsx` requires that a root layout is available as well, even if it's just passing `children` through.
+
+```tsx filename="app/layout.tsx"
+// Since we have a root `not-found.tsx` page, a layout file
+// is required, even if it's just passing children through.
+export default function RootLayout({children}) {
+ return children;
+}
+```
+
+For the 404 page to render, we need to call the `notFound` function within `[locale]/layout.tsx` when we detect an incoming `locale` param that isn't a valid locale.
+
+```tsx filename="app/[locale]/layout.tsx"
+import {useLocale} from 'next-intl';
+import {notFound} from 'next/navigation';
+
+const locales = ['en', 'de'];
+
+export default function LocaleLayout({children, params}) {
+ const locale = useLocale();
+
+ // Validate that the incoming `locale` parameter is a valid locale
+ if (params.locale !== locale) {
+ notFound();
+ }
+
+ return (
+ <html lang={locale}>
+ <body>{children}</body>
+ </html>
+ );
+}
+```
 
 ## `error.js`
 

diff --git a/docs/pages/docs/getting-started/app-router-server-components.mdx b/docs/pages/docs/getting-started/app-router-server-components.mdx
@@ -13,7 +13,7 @@ Next.js 13 introduces support for [React Server Components](https://nextjs.org/d
 ## Current beta version
 
 ```
-npm install [email protected].13
+npm install [email protected].14
 ```
 
 This beta version was tested with `[email protected]`.
@@ -130,7 +130,7 @@ import {notFound} from 'next/navigation';
 export default function LocaleLayout({children, params}) {
  const locale = useLocale();
 
- // Show a 404 error if the user requests an unknown locale
+ // Validate that the incoming `locale` parameter is a valid locale
  if (params.locale !== locale) {
  notFound();
  }