Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

πŸ“ Correct the i18n Trans guidance in CLAUDE.md (#2892)

Luke Vellab9ae87099a8d
diff --git a/CLAUDE.md b/CLAUDE.md
index 1e9bba832..80856a94e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -255,7 +255,7 @@ Reads filtered or grouped by the viewer's present ("upcoming", "past", agenda gr
import { Trans } from "@/i18n/client";
<Trans i18nKey="menu" defaults="Menu" />
```
-- On the server, use `getTranslation` from `@/i18n/server`:
+- When a server component needs `t` or `i18n` itself β€” for a string outside JSX, or to render `TransWithoutContext` β€” get them from `getTranslation` in `@/i18n/server` (rendering the client `Trans` instead needs neither; see below):
```tsx
import { Trans } from "react-i18next/TransWithoutContext";
import { getTranslation } from "@/i18n/server";
@@ -264,4 +264,9 @@ Reads filtered or grouped by the viewer's present ("upcoming", "past", agenda gr
t("menu", { defaultValue: "Menu" });
<Trans t={t} i18n={i18n} ns="app" i18nKey="menu" defaults="Menu" />;
```
- Server JSX must use `Trans` from `react-i18next/TransWithoutContext` (the context-ful `Trans` from `@/i18n/client` needs React context and cannot render in a server component) and must pass both `t` and `i18n` β€” omitting `i18n` falls back to the module-global instance, which can carry another request's language under concurrency.
\ No newline at end of file
+ Whenever you use `TransWithoutContext`, pass **both** `t` and `i18n` β€” omitting `i18n` falls back to the module-global instance, which can carry another request's language under concurrency.
+- **Per-request instances are what make this safe.** `apps/web` (`i18n/client.tsx`, `initI18next`) and `packages/emails` (`createEmailI18n`) both build a fresh instance per render via `createInstance()`, so nothing is shared between concurrent requests. Any new i18n entry point must do the same β€” never `import i18next from "i18next"` (the package default export is a process-wide singleton) and never mutate a shared instance with `changeLanguage()` to serve a request. `apps/landing/src/i18n/` currently violates this and is the one place where passing `i18n` does *not* help, because the `i18n` it hands you **is** the singleton.
+- **Where each `Trans` is required**, and where it's a free choice:
+ - **Emails** β€” `TransWithoutContext` only, with `t` and `i18n` from `createEmailI18n(locale)` (`packages/emails/src/i18n.ts`). Emails are sent from server components, where React context is unavailable, and each render builds its own locale-bound instance so a concurrent fan-out can't cross languages. Only a Next build catches a violation.
+ - **`app/global-error.tsx`** β€” neither. It renders outside the `[locale]` segment that mounts `I18nProvider`, so there is no locale and no `t`. Copy there is hardcoded English.
+ - **Everywhere else** β€” either import is correct. `I18nProvider` is mounted in `app/[locale]/layout.tsx`, the root layout, so every page (public poll pages included) is inside it. A server component *may* render the `"use client"` `Trans` from `@/i18n/client`: React serializes it as a client reference and the browser renders it against the per-tab instance, so there is no cross-request language bleed and no extra bundle weight (`react-i18next` is already loaded app-wide). Prefer `TransWithoutContext` in server components to keep static copy out of hydration, but don't make an otherwise-static page `async` just to do it β€” and don't file the client import as a bug.
\ No newline at end of file