Add language selector to site header

[zenoachtig]

• Rework the isMultiVariants property into a more comprehensive withVariants: "generic" | "translations" | undefined. This way simple checks can still be made against it (useful for search) but more specific checks on the type of variants can also be made.

  • Generic variants are now always shown inside the TOC. This reverts the behaviour of Consistently show variant selector in section bar if site has sections #3349.
  
  • Translations variants are shown in the header, either to the right of sections (if there are sections) or to the right of header links.
    

• Restyle the SpacesDropdown to use a <Button> instead of a custom component.

  • Translations variants get a SpacesDropdown with a globe 🌐 icon prepended to it. If the variant (= translation) starts with an emoji, we don't show the globe icon as we assume there's a flag to represent the language instead.

Fixes RND-8021, RND-5840

[changeset-bot]

🦋 Changeset detected

Latest commit: 564a2b7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
gitbook	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Summary of the deployments:

Version	URL	Status
Vercel	https://gitbook-v2-bu97msjk0-gitbook.vercel.app	✅
Cloudflare	https://f370dfb0-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-bu97msjk0-gitbook.vercel.app/url/gitbook.com/docs	https://f370dfb0-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-bu97msjk0-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://f370dfb0-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.gitbook.io/test-gitbook-open

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
customers-v2 (Inspect)	👍 Changes approved	41 changed	Sep 5, 2025, 12:10 PM
v2-cloudflare (Inspect)	👍 Changes approved	118 changed	Sep 5, 2025, 12:14 PM
v2-vercel (Inspect)	👍 Changes approved	119 changed	Sep 5, 2025, 12:13 PM

[linear]

RND-8021 Variant picker at beginning of sections list cuases layout shift

[linear]

RND-5840 Add language selector to GBO

[Copilot]

Pull Request Overview

This PR adds language selector functionality to the site header by reworking the variant system to distinguish between generic variants (shown in TOC) and translation variants (shown in header).

• Replaces isMultiVariants boolean with a more comprehensive withVariants: "generic" | "translations" | undefined property
• Positions translation variants in the site header (either next to sections or header links) while keeping generic variants in the TOC
• Refactors SpacesDropdown to use Button component and adds a new TranslationsDropdown with globe icon

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/gitbook/tailwind.config.ts	Comments out CSS variant for page-no-toc with variants
packages/gitbook/src/components/primitives/styles.ts	Adds button state styling for open dropdowns
packages/gitbook/src/components/primitives/DropdownMenu.tsx	Removes margin from dropdown chevron
packages/gitbook/src/components/primitives/Button.tsx	Exports ButtonProps type and adds styling classes for button icons
packages/gitbook/src/components/TableOfContents/TableOfContents.tsx	Updates CSS positioning for outline elements
packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx	Implements withVariants logic and updates variant positioning
packages/gitbook/src/components/RootLayout/globals.css	Adds site-background utility class
packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx	Uses new site-background utility class
packages/gitbook/src/components/Header/SpacesDropdown.tsx	Refactors to use Button component and adds TranslationsDropdown
packages/gitbook/src/components/Header/HeaderLink.tsx	Adds gap spacing to header link items
packages/gitbook/src/components/Header/Header.tsx	Integrates translation variants in header layout
.changeset/four-roses-live.md	Adds changeset for the feature

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}