docs: improve react-intl documentation for React Server Components (#3085)

## Summary

- Document `createIntl` from `@formatjs/intl` as the recommended
approach for i18n in Server Components — a context-free API with full
interpolation, pluralization, and date/number formatting
- Add limitations section for the plain `messages['key']` lookup pattern
(only works for pre-formatted strings, renders ICU `{variable}`
placeholders as literal text)
- Document Rails pre-formatting (`I18n.t('key', name: value)`) as a
valid alternative for Server Components
- Add comparison table reconciling build-time (`config.i18n_dir`) vs
controller-props i18n approaches
- Fix vague i18next claim in `rsc-third-party-libs.md` with concrete
per-request `createInstance()` guidance
- Add RSC cross-reference section to the build-time i18n docs
- Update compatibility decision matrix with `createIntl` recommendation

Fixes #3081

## Test plan

- [ ] Verify all internal markdown links resolve correctly
- [ ] Review `createIntl` code examples for accuracy against FormatJS
docs
- [ ] Confirm build-time vs controller-props comparison table is
accurate

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: documentation-only updates that don’t change runtime code,
limited to guidance/examples for i18n usage in RSC.
> 
> **Overview**
> Adds **React Server Components i18n guidance** across the docs,
recommending `react-intl`’s context-free `createIntl` API for Server
Components and documenting Rails-side pre-formatting as an alternative.
> 
> Clarifies the limitations of direct `messages['key']` lookups with ICU
placeholders, adds a build-time vs controller-props comparison table,
and updates the RSC third-party compatibility docs/matrix to reflect the
`createIntl` recommendation and more concrete `i18next` per-request
setup notes.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
eb62286. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added a comprehensive guide for internationalization with React Server
Components, recommending server-side formatting patterns and a
controller pre-formatting alternative.
* Reintroduced explicit client-side provider pattern for Client
Components.
* Added a build-time vs request-time comparison table and updated
third-party library compatibility guidance (including per-request
i18next considerations).
  * Expanded common mistakes with placeholder and formatting guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: justin808

docs/oss/building-features/i18n.md

@@ -183,6 +183,17 @@ By default, the locales are generated as JSON, but you can also generate them as
    )
    ```
 
+## Using i18n with React Server Components
+
+The build-time locale system described above generates flat dot-separated keys (e.g., `"product.title"`) and converts Rails `%{variable}` placeholders to ICU `{variable}` syntax. This works well with `react-intl`'s `defineMessages` in Client Components.
+
+For **Server Components**, `react-intl`'s hooks (`useIntl`) and Context (`IntlProvider`) are unavailable. Use one of these approaches:
+
+- **`createIntl` from `react-intl`** (recommended) — a context-free API that provides full interpolation, pluralization, and formatting in Server Components
+- **Rails pre-formatting** — compute `I18n.t('key', name: value)` in the controller and pass ready-to-render strings as props
+
+See the [RSC i18n Provider guide](../migrating/rsc-context-and-state.md#i18n-provider) for detailed patterns and code examples.
+
 ## Notes
 
 - See why using JSON can perform better compared to JS for large amounts of data [https://v8.dev/blog/cost-of-javascript-2019#json](https://v8.dev/blog/cost-of-javascript-2019#json).

docs/oss/migrating/rsc-context-and-state.md

@@ -353,7 +353,11 @@ If your React components also need the theme value, pass it as a prop:
 
 ### i18n Provider
 
-Internationalization in React on Rails typically uses Rails I18n on the server side and a client-side library (like `react-intl` or `i18next`) for Client Components. Pass translations from Rails as props:
+Internationalization in React on Rails typically uses Rails I18n on the server side and `react-intl` for Client Components. The challenge with RSC is that `react-intl`'s `useIntl()` hook and `<FormattedMessage>` component require React Context, which is unavailable in Server Components.
+
+> **Two i18n systems:** React on Rails has a [build-time locale system](../building-features/i18n.md) (`config.i18n_dir`) that compiles Rails YAML translations into JSON/JS files with flat dot-separated keys (e.g., `"product.title"`). The controller-props approach below passes translations at request time with whatever key structure you choose. Both are valid — see the comparison below.
+
+#### Passing translations from Rails
 
 ```ruby
 # app/controllers/application_controller.rb
@@ -369,32 +373,43 @@ def i18n_props
 end
 ```
 
-```jsx
-// I18nProvider.jsx
-'use client';
+#### Server Components: plain string lookup (limited)
 
-import { IntlProvider } from 'react-intl';
+The simplest approach is to read translation values directly from the messages object:
 
-export default function I18nProvider({ locale, messages, children }) {
-  return (
-    <IntlProvider locale={locale} messages={messages}>
-      {children}
-    </IntlProvider>
-  );
+```jsx
+// ProductPage.jsx -- Server Component
+export default function ProductPage({ locale, messages, ...props }) {
+  const title = messages['title'];
+
+  return <h1>{title}</h1>;
 }
 ```
 
+> **Limitation:** This only works for **pre-formatted strings** — plain text with no interpolation, pluralization, or number/date formatting. React on Rails' build-time locale system converts Rails `%{variable}` placeholders to ICU `{variable}` syntax, so `messages['greeting']` would render the literal text `{name}` instead of a substituted value. For anything beyond plain strings, use `createIntl` or Rails pre-formatting (both described below).
+
+#### Server Components: `createIntl` from `react-intl` (recommended)
+
+Import `createIntl` from `react-intl` for a **context-free API** that provides full interpolation, pluralization, and date/number formatting without React Context. This is the recommended approach for i18n in Server Components:
+
 ```jsx
 // ProductPage.jsx -- Server Component
+import { createIntl, createIntlCache } from 'react-intl';
 import I18nProvider from './I18nProvider';
 
+// Module-level cache — safe because it only caches Intl constructors, not request data
+const cache = createIntlCache();
+
 export default function ProductPage({ locale, messages, ...props }) {
-  // Server Components can use the translations object directly
-  const title = messages['title'];
+  const intl = createIntl({ locale, messages }, cache);
 
   return (
     <div>
-      <h1>{title}</h1>
+      {/* Full formatting works in Server Components */}
+      <h1>{intl.formatMessage({ id: 'greeting' }, { name: props.userName })}</h1>
+      <p>{intl.formatNumber(props.price, { style: 'currency', currency: 'USD' })}</p>
+      <p>{intl.formatMessage({ id: 'items_count' }, { count: props.itemCount })}</p>
+
       <I18nProvider locale={locale} messages={messages}>
         <InteractiveFilters /> {/* Client Component can use useIntl() */}
       </I18nProvider>
@@ -403,6 +418,44 @@ export default function ProductPage({ locale, messages, ...props }) {
 }
 ```
 
+> **Note:** `createIntl` is a plain function call — no hooks, no Context, no `'use client'` needed. The `createIntlCache()` call avoids recreating expensive `Intl.NumberFormat` / `Intl.DateTimeFormat` instances on every request. The cache stores only `Intl` constructor instances keyed by format options — no locale data, messages, or user-specific information — so it is safe to share at module scope across all concurrent requests for the lifetime of the Node.js process.
+
+#### Alternative: Rails pre-formatting
+
+Instead of formatting on the client, let Rails compute interpolation and pluralization before passing translations as props. This keeps Server Components simple at the cost of less flexible client-side formatting:
+
+```ruby
+def i18n_props
+  {
+    locale: I18n.locale.to_s,
+    # Pre-format with variables — Server Components receive ready-to-render strings
+    greeting: I18n.t('greeting', name: current_user.name),
+    items_count: I18n.t('items_count', count: @cart.item_count),
+    # Pass raw messages for Client Components that need dynamic formatting
+    messages: I18n.t('product_page').deep_stringify_keys,
+  }
+end
+```
+
+#### Client Components: `IntlProvider` + `useIntl()`
+
+Client Components use the standard `react-intl` Context pattern:
+
+```jsx
+// I18nProvider.jsx
+'use client';
+
+import { IntlProvider } from 'react-intl';
+
+export default function I18nProvider({ locale, messages, children }) {
+  return (
+    <IntlProvider locale={locale} messages={messages}>
+      {children}
+    </IntlProvider>
+  );
+}
+```
+
 ```jsx
 // InteractiveFilters.jsx -- Client Component
 'use client';
@@ -415,6 +468,15 @@ export default function InteractiveFilters() {
 }
 ```
 
+#### Build-time vs controller-props: when to use each
+
+| Approach                       | Source                     | Key format                      | Best for                                                                                |
+| ------------------------------ | -------------------------- | ------------------------------- | --------------------------------------------------------------------------------------- |
+| Build-time (`config.i18n_dir`) | YAML → compiled JSON/JS    | Flat: `"product.title"`         | Static translations shared across pages; client-side `react-intl` with `defineMessages` |
+| Controller-props (`I18n.t`)    | Rails I18n at request time | Flat (required by `createIntl`) | Page-specific translations; pre-formatted strings with variables; RSC `createIntl`      |
+
+Both can be used together — for example, build-time translations for the client bundle and controller-props for Server Component content. See the [Internationalization guide](../building-features/i18n.md) for build-time setup details.
+
 ## Common Mistakes
 
 ### Mistake 1: Wrapping the entire tree in providers unnecessarily
@@ -468,7 +530,24 @@ messages: I18n.t('.').deep_stringify_keys
 messages: I18n.t('product_page').deep_stringify_keys
 ```
 
-### Mistake 3: Reading Redux store in Server Components
+### Mistake 3: Using `messages['key']` for translations with placeholders
+
+The build-time locale system converts Rails `%{variable}` placeholders to ICU `{variable}` syntax. Reading these directly from the messages object renders the literal placeholder text:
+
+```jsx
+// BAD: Renders "Hello, {name}" as literal text
+const greeting = messages['greeting'];
+```
+
+```jsx
+// GOOD: Use createIntl to format with variable substitution
+import { createIntl, createIntlCache } from 'react-intl';
+const cache = createIntlCache();
+const intl = createIntl({ locale, messages }, cache);
+const greeting = intl.formatMessage({ id: 'greeting' }, { name: 'John' });
+```
+
+### Mistake 4: Reading Redux store in Server Components
 
 Server Components render once on the server and never re-render. They cannot subscribe to store changes:
 
@@ -482,7 +561,7 @@ export default function Dashboard({ user }) {
 
 **Fix:** Keep the component as a Client Component (add `'use client'`), or pass the value from Rails as a prop to a Server Component that doesn't need the Redux store.
 
-### Mistake 4: Creating new QueryClient on every render
+### Mistake 5: Creating new QueryClient on every render
 
 If the `QueryClient` is created without `useState`, React creates a new instance on every render, losing the cache:
 

docs/oss/migrating/rsc-third-party-libs.md

@@ -251,10 +251,10 @@ All major date libraries work in Server Components since they are pure utility f
 
 ## Internationalization
 
-| Library                     | RSC Pattern                                                                                                                                                     | Notes                                                                                        |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| **Rails I18n + react-intl** | Pass translations from Rails controller as props. Server Components use the translations object directly; Client Components use `<IntlProvider>` + `useIntl()`. | Recommended for React on Rails. See [Context guide](rsc-context-and-state.md#i18n-provider). |
-| **i18next / react-i18next** | Requires `'use client'` for hook-based usage. Server Components can use `i18next` directly (no hooks).                                                          | Framework-agnostic alternative.                                                              |
+| Library                     | RSC Pattern                                                                                                                                                                                                                                            | Notes                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| **Rails I18n + react-intl** | Pass translations from Rails controller as props. Server Components use `createIntl` from `react-intl` for full formatting (interpolation, pluralization, dates); Client Components use `<IntlProvider>` + `useIntl()`.                                | Recommended for React on Rails. See [Context guide](rsc-context-and-state.md#i18n-provider). |
+| **i18next / react-i18next** | `react-i18next` hooks (`useTranslation`) require `'use client'`. For Server Components, `i18next` can be initialized per-request via `i18next.createInstance()` and used without hooks — but you must manage locale/namespace initialization yourself. | Requires per-request setup; not used in this codebase.                                       |
 
 ## Authentication
 
@@ -364,7 +364,7 @@ Use `client-only` for:
 | **Charts**        | Nivo (SSR support)                                                | Recharts, Tremor, Chart.js                   | --                                                 |
 | **Data Fetching** | React on Rails Pro streaming, native `fetch` in Server Components | TanStack Query (with hydration), Apollo, SWR | --                                                 |
 | **State**         | Server Component props, `React.cache`                             | Zustand, Jotai (v2.6+), Redux Toolkit        | Recoil (discontinued)                              |
-| **i18n**          | Rails I18n + react-intl                                           | react-i18next, i18next                       | --                                                 |
+| **i18n**          | Rails I18n + `createIntl` (Server), `IntlProvider` (Client)       | react-i18next (hooks require `'use client'`) | --                                                 |
 | **Auth**          | Rails auth (Devise, etc.) via controller props                    | --                                           | --                                                 |
 | **Date Utils**    | date-fns, dayjs (pure functions)                                  | --                                           | Moment.js (not tree-shakable)                      |