docs: Explain passing rich text functions in defaultTranslationMessages to NextIntlClientProvider (#878 by @janoschherrmann)

Closes #865

---------

Co-authored-by: Jan Amann <jan@amann.me>

Author: janoschherrmann

docs/pages/docs/usage/configuration.mdx

@@ -380,7 +380,7 @@ function Component() {
 
 ## Default translation values
 
-To achieve consistent usage of translation values and reduce redundancy, you can define a set of global default values. This configuration can also be used to apply consistent styling of commonly used rich text elements.
+To achieve consistent usage of translation values and reduce redundancy, you can define a set of global default values. This configuration can also be used to apply consistent styling of commonly used rich text elements. In case you provide values at a specific call site of `t`, these will potentially override global defaults.
 
 <Tabs items={['i18n.ts', 'Provider']}>
 <Tab>
@@ -414,11 +414,38 @@ export default getRequestConfig(async ({locale}) => {
 </NextIntlClientProvider>
 ```
 
+Note that `NextIntlClientProvider` is a Client Component, therefore if you render it from a Server Component, the props need to be [serializable](https://react.dev/reference/react/use-client#serializable-types) across the server/client boundary.
+
+If you provide rich text element functions, this means that you should render the provider along with the configuration for `defaultTranslationValues` from a component that is marked with `'use client'`:
+
+```tsx filename="Provider.tsx"
+// Making this a Client Component allows us to provide
+// non-serializable props to `NextIntlClientProvider`
+'use client';
+
+import {NextIntlClientProvider} from 'next-intl';
+
+export default function Provider({messages, children}) {
+  return (
+    <NextIntlClientProvider
+      // Passing functions as props is fine here!
+      defaultTranslationValues={{
+        important: (chunks) => <b>{chunks}</b>
+      }}
+      // Forward messages from the server side
+      messages={messages}
+    >
+      {children}
+    </NextIntlClientProvider>
+  );
+}
+```
+
+In this case, `messages` should be provided from a Server Component, potentially as returned from the [`useMessages`](/docs/usage/configuration#messages) hook.
+
 </Tab>
 </Tabs>
 
-The defaults will be overridden if local formats are provided at a specific call site.
-
 ## Error handling
 
 By default, when a message fails to resolve or when the formatting failed, an error will be printed on the console. In this case `${namespace}.${key}` will be rendered instead to keep your app running.
@@ -456,7 +483,7 @@ export default getRequestConfig(async ({locale}) => {
     }
   };
 });
-````
+```
 
 </Tab>
 <Tab>

docs/theme.config.tsx

@@ -1,6 +1,5 @@
 import Footer from 'components/Footer';
 import PartnerSidebar from 'components/PartnerSidebar';
-import Link from 'next/link';
 import {useRouter} from 'next/router';
 import {ThemeConfig} from 'nextra';
 import {Navbar, ThemeSwitch, useConfig} from 'nextra-theme-docs';
@@ -83,17 +82,6 @@ export default {
       titleTemplate: '%s – Internationalization (i18n) for Next.js'
     };
   },
-  banner: {
-    text: (
-      <>
-        next-intl 3.0 is out! (
-        <Link className="underline" href="/blog/next-intl-3-0">
-          announcement
-        </Link>
-        )
-      </>
-    )
-  },
   primaryHue: {light: 210, dark: 195},
   footer: {
     component: Footer

packages/next-intl/src/react-server/NextIntlClientProvider.tsx packages/next-intl/src/react-server/NextIntlClientProviderServer.tsx

@@ -4,7 +4,7 @@ import BaseNextIntlClientProvider from '../shared/NextIntlClientProvider';
 
 type Props = ComponentProps<typeof BaseNextIntlClientProvider>;
 
-export default async function NextIntlClientProvider({
+export default async function NextIntlClientProviderServer({
   locale,
   now,
   timeZone,

packages/next-intl/src/react-server/index.tsx

@@ -13,7 +13,7 @@ export {default as useFormatter} from './useFormatter';
 export {default as useNow} from './useNow';
 export {default as useTimeZone} from './useTimeZone';
 export {default as useMessages} from './useMessages';
-export {default as NextIntlClientProvider} from './NextIntlClientProvider';
+export {default as NextIntlClientProvider} from './NextIntlClientProviderServer';
 
 // Everything from `core`
 export * from 'use-intl/core';

packages/next-intl/test/react-server/NextIntlClientProvider.test.tsx packages/next-intl/test/react-server/NextIntlClientProviderServer.test.tsx

@@ -1,7 +1,7 @@
 import {expect, it, vi} from 'vitest';
-import NextIntlClientProvider from '../../src/react-server/NextIntlClientProvider';
+import NextIntlClientProviderServer from '../../src/react-server/NextIntlClientProviderServer';
 import {getLocale, getNow, getTimeZone} from '../../src/server.react-server';
-import BaseNextIntlClientProvider from '../../src/shared/NextIntlClientProvider';
+import NextIntlClientProvider from '../../src/shared/NextIntlClientProvider';
 
 vi.mock('../../src/server/react-server', async () => ({
   getLocale: vi.fn(async () => 'en-US'),
@@ -14,14 +14,14 @@ vi.mock('../../src/shared/NextIntlClientProvider', async () => ({
 }));
 
 it("doesn't read from headers if all relevant configuration is passed", async () => {
-  const result = await NextIntlClientProvider({
+  const result = await NextIntlClientProviderServer({
     children: null,
     locale: 'en-GB',
     now: new Date('2020-02-01T00:00:00.000Z'),
     timeZone: 'Europe/London'
   });
 
-  expect(result.type).toBe(BaseNextIntlClientProvider);
+  expect(result.type).toBe(NextIntlClientProvider);
   expect(result.props).toEqual({
     children: null,
     locale: 'en-GB',
@@ -35,11 +35,11 @@ it("doesn't read from headers if all relevant configuration is passed", async ()
 });
 
 it('reads missing configuration from getter functions', async () => {
-  const result = await NextIntlClientProvider({
+  const result = await NextIntlClientProviderServer({
     children: null
   });
 
-  expect(result.type).toBe(BaseNextIntlClientProvider);
+  expect(result.type).toBe(NextIntlClientProvider);
   expect(result.props).toEqual({
     children: null,
     locale: 'en-US',