feat!: Next.js 13 RSC integration

docs/next.config.js

@@ -26,7 +26,7 @@ module.exports = withNextra({
     },
     {
       source: '/examples',
-      destination: '/examples/minimal',
+      destination: '/examples/next-13',
       permanent: false
     },
 

docs/pages/blog/index.mdx

@@ -15,6 +15,8 @@ Failed attempts at writing docs that somehow turned into blog posts.
 
 ## Community links
 
+Resources on `next-intl` created by and for the community.
+
 <div className="flex flex-col gap-4 py-8">
   <CommunityLink
     href="https://www.smashingmagazine.com/2023/03/internationalization-nextjs-13-react-server-components/"
@@ -24,6 +26,14 @@ Failed attempts at writing docs that somehow turned into blog posts.
     target="_blank"
     type="article"
   />
+  <CommunityLink
+    href="https://buttercms.com/blog/nextjs-localization/"
+    title="Next.js Localization: How to Build a Multilingual Website with next-intl"
+    date="Nov 4, 2021"
+    author="By Nirmalya Ghosh for ButterCMS"
+    target="_blank"
+    type="article"
+  />
   <CommunityLink
     href="https://www.thisdot.co/blog/next-js-adding-localization-with-next-intl"
     title="Next.js: Adding Localization with next-intl"

docs/pages/blog/translations-outside-of-react-components.mdx

@@ -6,7 +6,7 @@ title: How (not) to use translations outside of React components
 
 Have you ever wondered why `next-intl` doesn’t provide an API to consume translations outside of React components?
 
-The traditional way is to use the `useTranslations` hook.
+The traditional way to internationalize your app with `next-intl` is to use the `useTranslations` hook:
 
 ```tsx
 import {useTranslations} from 'next-intl';
@@ -34,8 +34,10 @@ import {addMinutes} from 'date-fns';
 function sendFeedback() {
   // ❌ Bad implementation: Returns formatted messages
   API.sendFeedback().catch((error) => {
+    // In case of a gateway timeout, notify the
+    // user that we'll try again in 5 minutes
     if (error.status === 504) {
-      // Notify the user that we'll try again in 5 minutes
+      // (let's assume `t` is defined here for the sake of the example)
       return t('timeout', {nextAttempt: addMinutes(new Date(), 5)});
     }
   });
@@ -107,7 +109,7 @@ Additionally, this approach is more robust to possibly unexpected states, like t
 
 ## The exception that proves the rule
 
-If you’re working with Next.js, you might like to translate i18n messages in [API routes](https://nextjs.org/docs/api-routes/introduction), [Route Handlers](https://beta.nextjs.org/docs/routing/route-handlers) or the [Metadata API](https://beta.nextjs.org/docs/api-reference/metadata).
+If you’re working with Next.js, you might want to translate i18n messages in [API routes](https://nextjs.org/docs/api-routes/introduction), [Route Handlers](https://beta.nextjs.org/docs/routing/route-handlers) or the [Metadata API](https://beta.nextjs.org/docs/api-reference/metadata).
 
 `next-intl` provides a [core library](/docs/usage/core-library) that is agnostic from React and can be used for these cases.
 
@@ -133,6 +135,6 @@ There's currently a proposal to further simplify this use case, by offering a se
 
 If you’ve been working with React for a longer time, you might have experienced the change [from `component{DidMount,DidUpdate,WillUnmount}` to `useEffect`](https://legacy.reactjs.org/docs/hooks-effect.html#explanation-why-effects-run-on-each-update). The reason why `useEffect` is superior is because it nudges the developer into a direction where the app is always in sync and by doing this, a whole array of potential issues just magically disappear.
 
-By limiting ourselves to only format messages during render, we're in a similar situation: The rendered output of translated messages is always in sync with app state.
+By limiting ourselves to only format messages during render, we're in a similar situation: The rendered output of translated messages is always in sync with app state and we can rely on the app being consistent.
 
 Related: ["How can I reuse messages?" in the structuring messages docs](/docs/usage/messages#structuring-messages)

docs/pages/docs/next-13/_meta.json

@@ -2,5 +2,6 @@
   "index": "Getting started",
   "client-components": "Client Components",
   "server-components": "Server Components (beta)",
-  "middleware": "Middleware"
+  "middleware": "Middleware",
+  "navigation": "Navigation"
 }

docs/pages/docs/next-13/client-components.mdx

@@ -121,54 +121,6 @@ If you've encountered an issue, you can [explore the code for a working example]
   version](/docs/next-13/server-components).
 </Callout>
 
-## Linking between pages
-
-In the `pages` folder, Next.js automatically considers the current locale for `next/link`. Since this is no longer the case for the `app` directory, you can add a component that wraps `next/link` accordingly as a drop-in replacement.
-
-```tsx filename="Link.tsx"
-import {useLocale} from 'next-intl';
-import NextLink from 'next/link';
-import {ComponentProps, forwardRef} from 'react';
-
-type Props = ComponentProps<typeof NextLink>;
-
-function Link({href, ...rest}: Props, ref: Props['ref']) {
-  const locale = useLocale();
-
-  // Turn this off, to avoid updating the locale cookie for prefetch requests
-  const prefetch = false;
-
-  function getLocalizedHref(originalHref: string) {
-    return originalHref.replace(/^\//, '/' + locale + '/');
-  }
-
-  const localizedHref =
-    typeof href === 'string'
-      ? getLocalizedHref(href)
-      : href.pathname != null
-      ? {...href, pathname: getLocalizedHref(href.pathname)}
-      : href;
-
-  return (
-    <NextLink ref={ref} href={localizedHref} prefetch={prefetch} {...rest} />
-  );
-}
-
-export default forwardRef(Link);
-```
-
-```tsx
-// Usage while being on `/en`
-<Link href="/">Goes to `/en`</Link>
-<Link href="/nested">Goes to `/en/nested`</Link>
-<Link href={{pathname: "/nested"}}>Goes to `/en/nested`</Link>
-```
-
-<Callout>
-  Built-in support for i18n routing APIs is being considered (see [the Server
-  Components beta docs](/docs/next-13/server-components#routing)).
-</Callout>
-
 ## Usage with the Metadata API
 
 To provide metadata for a route, you can use the [core library](/docs/usage/core-library) from `next-intl`.

docs/pages/docs/next-13/index.mdx

@@ -41,7 +41,7 @@ To fill in the gaps and to leverage the new capabilities, `next-intl` now suppor
   <Card
     arrow
     icon={<LinkIcon />}
-    title="Localized routing APIs (beta)"
-    href="/docs/next-13/server-components#routing"
+    title="Localized navigation APIs"
+    href="/docs/next-13/navigation"
   />
 </Cards>

docs/pages/docs/next-13/middleware.mdx

@@ -199,7 +199,7 @@ module.exports = withNextIntl({
 
 Since `next-intl` isn't aware of the rewrites you've configured, you likely want to make some adjustments:
 
-1. Translate the pathnames you're passing to routing APIs like `Link` based on the `locale`. See the [named routes example](https://github.com/amannn/next-intl/blob/feat/next-13-rsc/packages/example-next-13-named-routes/) that uses the proposed [routing APIs from the Server Components beta](http://localhost:3000/docs/next-13/server-components#routing).
+1. Translate the pathnames you're passing to [navigation APIs](/docs/next-13/navigation) like `Link` based on the `locale`. See the [named routes example](https://github.com/amannn/next-intl/blob/feat/next-13-rsc/packages/example-next-13-named-routes/) that uses the proposed APIs from [the Server Components beta](http://localhost:3000/docs/next-13/server-components).
 2. Turn off [the `alternateLinks` option](/docs/next-13/middleware#disable-alternate-links) and provide [search engine hints about localized versions of your content](https://developers.google.com/search/docs/specialty/international/localized-versions) by yourself.
 
 ## Composing other middlewares

docs/pages/docs/next-13/navigation.mdx

@@ -0,0 +1,71 @@
+import Callout from 'components/Callout';
+
+# Next.js 13 internationalized navigation
+
+`next-intl` provides drop-in replacements for common Next.js navigation APIs that automatically handle the user locale behind the scenes.
+
+### `Link`
+
+This component wraps `next/link` and automatically prefixes the `href` with the current locale as necessary. If the default locale is matched, the `href` remains unchanged and no prefix is added.
+
+```tsx
+import {Link} from 'next-intl';
+
+// When the user is on `/en`, the link will point to `/en/about`
+<Link href="/about">About</Link>
+
+// You can override the `locale` to switch to another language
+<Link href="/" locale="de">Switch to German</Link>
+```
+
+### `useRouter`
+
+If you need to navigate programmatically, e.g. in response to a form submission, `next-intl` provides a convience API that wraps `useRouter` from Next.js and automatically applies the locale of the user.
+
+```tsx
+'use client';
+
+import {useRouter} from 'next-intl/client';
+
+const router = useRouter();
+
+// When the user is on `/en`, the router will navigate to `/en/about`
+router.push('/about');
+```
+
+### `usePathname`
+
+To retrieve the pathname without a potential locale prefix, you can call `usePathname`.
+
+```tsx
+'use client';
+
+import {usePathname} from 'next-intl/client';
+
+// When the user is on `/en`, this will be `/`
+const pathname = usePathname();
+```
+
+### `redirect`
+
+<Callout type="warning">
+  This API is only available in [the Server Components
+  beta](/docs/next-13/server-components).
+</Callout>
+
+If you want to interrupt the render of a Server Component and redirect to another page, you can invoke the `redirect` function from `next-intl/server`. This wraps [the `redirect` function from Next.js](https://beta.nextjs.org/docs/api-reference/redirect) and automatically applies the current locale.
+
+```tsx {1, 8}
+import {redirect} from 'next-intl/server';
+
+export default async function Profile() {
+  const user = await fetchUser();
+
+  if (!user) {
+    // When the user is on `/en/profile`, this will be `/en/login`
+    redirect('/login');
+  }
+
+  // ...
+}
+```

docs/pages/docs/next-13/server-components.mdx

@@ -167,71 +167,6 @@ If you've encountered an issue, you can [explore the code for a working example]
 
 If you're in a transitioning phase, either from the `pages` directory to the `app` directory, or from Client Components to the Server Components beta, you can apply [`NextIntlClientProvider`](/docs/next-13/client-components) additionally ([example](https://github.com/amannn/next-intl/tree/feat/next-13-rsc/packages/example-next-13-with-pages)).
 
-## Routing
-
-`next-intl` provides drop-in replacements for common Next.js routing APIs that automatically handle the user locale behind the scenes.
-
-### `Link`
-
-`next-intl` provides a drop-in replacement for `next/link` that will automatically prefix the `href` with the current locale as necessary. If the default locale is matched, the `href` remains unchanged and no prefix is added.
-
-```tsx
-import {Link} from 'next-intl';
-
-// When the user is on `/en`, the link will point to `/en/about`
-<Link href="/about">About</Link>
-
-// You can override the `locale` to switch to another language
-<Link href="/" locale="de">Switch to German</Link>
-```
-
-### `useRouter`
-
-If you need to navigate programmatically (e.g. in response to a form submission), `next-intl` provides a convience API that wraps `useRouter` from Next.js and automatically applies the locale of the user.
-
-```tsx
-'use client';
-
-import {useRouter} from 'next-intl/client';
-
-const router = useRouter();
-
-// When the user is on `/en`, the router will navigate to `/en/about`
-router.push('/about');
-```
-
-### `usePathname`
-
-To retrieve the pathname without a potential locale prefix, you can call `usePathname`.
-
-```tsx
-'use client';
-
-import {usePathname} from 'next-intl/client';
-
-// When the user is on `/en`, this will be `/`
-const pathname = usePathname();
-```
-
-### `redirect`
-
-If you want to interrupt the render of a Server Component and redirect to another page, you can invoke the `redirect` function from `next-intl/server`. This wraps [the `redirect` function from Next.js](https://beta.nextjs.org/docs/api-reference/redirect) and automatically applies the current locale.
-
-```tsx {1, 8}
-import {redirect} from 'next-intl/server';
-
-export default async function Profile() {
-  const user = await fetchUser();
-
-  if (!user) {
-    // When the user is on `/en/profile`, this will be `/en/login`
-    redirect('/login');
-  }
-
-  // ...
-}
-```
-
 ## Using translations in Client Components
 
 If you need to use translations or other functionality from `next-intl` in Client Components, the best approach is to pass the labels as props or `children` from a Server Component.
@@ -395,6 +330,8 @@ import {
 } from 'next-intl/server';
 ```
 
+Note however that the `useTranslations` hook is the primary API to translate messages in your app. Related: [How (not) to use translations outside of React components](/blog/translations-outside-of-react-components)
+
 ## CDN caching
 
 Since `next-intl` is currently SSR-only, it's a good idea to use [CDN caching](https://vercel.com/docs/concepts/edge-network/caching#stale-while-revalidate) via [`headers`](https://nextjs.org/docs/api-reference/next.config.js/headers) in `next.config.js` to get the same level of performance from dynamic rendering as you'd get from static rendering ([learn more](https://youtu.be/bfLFHp7Sbkg?t=490)). Also note that [the Next.js Cache](https://nextjs.org/blog/next-13-2#nextjs-cache) improves the performance for dynamically rendered pages.
@@ -435,6 +372,11 @@ module.exports = withNextIntl({
 });
 ```
 
+<Callout type="warning">
+  Unfortunately, this doesn't work anymore in Next.js 13.4. An alternative is
+  being investigated.
+</Callout>
+
 ## Providing feedback
 
 If you have feedback about using `next-intl` in the `app` directory, feel free to leave feedback in [the PR which implements the React Server Components support](https://github.com/amannn/next-intl/pull/149).

docs/pages/examples/_meta.json

@@ -1,10 +1,14 @@
 {
+  "next-13": {
+    "title": "App Router",
+    "theme": {"layout": "full"}
+  },
   "minimal": {
-    "title": "Minimal setup",
+    "title": "Pages Router",
     "theme": {"layout": "full"}
   },
   "advanced": {
-    "title": "Advanced usage",
+    "title": "Pages Router (advanced)",
     "theme": {"layout": "full"}
   }
 }

docs/pages/examples/advanced.mdx

@@ -1,11 +1,11 @@
 ---
-title: Advanced usage
+title: Pages Router (advanced)
 full: true
 ---
 
 import CodeSandbox from '../../components/CodeSandbox';
 
 <CodeSandbox
-  title="Advanced usage"
+  title="Pages Router (advanced)"
   src="https://codesandbox.io/s/github/amannn/next-intl/tree/main/examples/example-advanced?file=/src/pages/index.tsx"
 />

docs/pages/examples/minimal.mdx

@@ -1,11 +1,11 @@
 ---
-title: Minimal setup
+title: Pages Router
 full: true
 ---
 
 import CodeSandbox from '../../components/CodeSandbox';
 
 <CodeSandbox
-  title="Minimal setup"
+  title="Pages Router"
   src="https://codesandbox.io/s/github/amannn/next-intl/tree/main/examples/example?file=/src/pages/index.tsx"
 />

docs/pages/examples/next-13.mdx

@@ -0,0 +1,11 @@
+---
+title: App Router
+full: true
+---
+
+import CodeSandbox from '../../components/CodeSandbox';
+
+<CodeSandbox
+  title="App Router"
+  src="https://codesandbox.io/s/github/amannn/next-intl/tree/main/examples/example-next-13?file=/src/app/[locale]/page.tsx"
+/>

examples/example-next-13-advanced/playwright.config.ts

@@ -3,7 +3,7 @@ import type {PlaywrightTestConfig} from '@playwright/test';
 import {devices} from '@playwright/test';
 
 // Use a distinct port on CI to avoid conflicts during concurrent tests
-const PORT = process.env.CI ? 3001 : 3000;
+const PORT = process.env.CI ? 3003 : 3000;
 
 const config: PlaywrightTestConfig = {
   testDir: './tests',

examples/example-next-13-named-routes/playwright.config.ts

@@ -3,7 +3,7 @@ import type {PlaywrightTestConfig} from '@playwright/test';
 import {devices} from '@playwright/test';
 
 // Use a distinct port on CI to avoid conflicts during concurrent tests
-const PORT = process.env.CI ? 3003 : 3000;
+const PORT = process.env.CI ? 3004 : 3000;
 
 const config: PlaywrightTestConfig = {
   testDir: './tests',