fix(react): allow explicit locale for static server rendering

[floze-the-genius]

Summary

• allow createServerInstance callers to pass an explicit locale to getTolgee and getTranslate
• avoid invoking request-bound locale detection when route params already provide the locale
• add an App Router generateStaticParams regression route and example guidance

Reproduction

Before the change, the regression route failed during next build with:

Route /[locale]/ssg with `dynamic = "error"` couldn't be rendered statically because it used `headers`.

After passing the route locale to getTolgee(locale), Next emits /en/ssg, /cs/ssg, /de/ssg, and /fr/ssg as SSG pages.

Tests

• pnpm --filter @tolgee/react test -- --runInBand
• pnpm --filter @tolgee/react build
• pnpm --dir testapps/next-app-intl build
• focused ESLint and Prettier checks

Closes #3526

Summary by CodeRabbit

• New Features
  • Added optional locale selection when loading Tolgee and fetching translations (including passing locale via the server T component).
  • Updated locale-based rendering to use the route’s locale directly.
  • Added a statically generated page for each supported locale.
• Documentation
  • Added guidance for providing explicit locales during static rendering to avoid locale resolver execution.
• Tests
  • Added coverage for default vs explicit locale behavior, including server T locale handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c9f7d2c7-252c-44a0-92bb-9ae1ca67b8dd

📥 Commits

Reviewing files that changed from the base of the PR and between 7164155 and 4a96ccc.

📒 Files selected for processing (2)

• packages/react/src/createServerInstance.spec.tsx
• packages/react/src/createServerInstance.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/react/src/createServerInstance.tsx

---

Walkthrough

createServerInstance now accepts explicit locales for Tolgee creation and translation lookup. Tests cover both locale resolution paths. The Next.js example passes route locales into the server instance and adds a statically generated locale page with supporting documentation.

Changes

Server locale rendering

Layer / File(s)	Summary
Explicit locale resolution and tests packages/react/src/createServerInstance.tsx, packages/react/src/createServerInstance.spec.tsx	getTolgee, getTranslate, and T accept optional locales, with tests covering resolver-based and explicit-locale behavior.
Next.js static locale integration testapps/next-app-intl/src/app/[locale]/layout.tsx, testapps/next-app-intl/src/app/[locale]/ssg/page.tsx, testapps/next-app-intl/README.md	The localized layout passes its route locale to getTolgee; a locale-scoped static page and usage documentation are added.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant StaticRoute
  participant LocaleLayout
  participant createServerInstance
  participant Tolgee
  StaticRoute->>LocaleLayout: provide locale route param
  LocaleLayout->>createServerInstance: call getTolgee(locale)
  createServerInstance->>Tolgee: create or retrieve locale instance
  Tolgee-->>LocaleLayout: return configured instance

Loading

Poem

I’m a bunny with a locale to choose,
No headers to nibble, no routes to confuse.
Static pages hop from params so bright,
Tolgee brings the proper words just right.
Tests thump softly: the flow is sound!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: explicit locale support for static server rendering.
Linked Issues check	✅ Passed	The changes add explicit locale support, a static App Router example, and docs that address #3526's SSG/ISR requirement.
Out of Scope Changes check	✅ Passed	All changes support the static-rendering locale workflow; no unrelated code paths appear added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/react/src/createServerInstance.tsx (1)

38-41: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Support explicit locale in the Server <T> component.

Since getTranslate now supports an explicit locale to bypass getLocale() (and avoid request-bound headers() usage that breaks static generation), the Server <T> component will still fail during static generation because it calls getTranslate() without arguments.

Consider adding an optional locale prop to the server <T> component (e.g., by extending TProps or extracting it from the props) so users can safely use <T> in statically generated Server Components.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/react/src/createServerInstance.tsx` around lines 38 - 41, Add an
optional locale prop to the server T component’s props and pass it to
getTranslate, preserving the existing locale-resolution behavior when the prop
is omitted so static generation can bypass request-bound locale detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@packages/react/src/createServerInstance.tsx`:
- Around line 38-41: Add an optional locale prop to the server T component’s
props and pass it to getTranslate, preserving the existing locale-resolution
behavior when the prop is omitted so static generation can bypass request-bound
locale detection.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: afd64097-7f98-4935-9361-73c3ebb1deb4

📥 Commits

Reviewing files that changed from the base of the PR and between 322a726 and 7164155.

📒 Files selected for processing (5)

• packages/react/src/createServerInstance.spec.tsx
• packages/react/src/createServerInstance.tsx
• testapps/next-app-intl/README.md
• testapps/next-app-intl/src/app/[locale]/layout.tsx
• testapps/next-app-intl/src/app/[locale]/ssg/page.tsx