Skip to content

docs(next): document the NEXT_LOCALE override in headersAndCookies - #427

Closed
moss-bryophyta wants to merge 1 commit into
mainfrom
docs/next-locale-cookie-override
Closed

docs(next): document the NEXT_LOCALE override in headersAndCookies#427
moss-bryophyta wants to merge 1 commit into
mainfrom
docs/next-locale-cookie-override

Conversation

@moss-bryophyta

Copy link
Copy Markdown
Contributor

What

The headersAndCookies reference in the Next.js config page says every field "defaults to the library's standard name." Since gt-next@11.1.3 (generaltranslation/gt#2004) that is incomplete: withGTConfig repoints localeCookieName at NEXT_LOCALE whenever the Next.js config sets i18n and leaves localeDetection enabled, so Pages Router locale persistence matches the cookie the router actually reads.

The part worth calling out

The override is applied after props.headersAndCookies in the merge:

const mergedHeadersAndCookies = {
  ...defaultWithGTConfigProps.headersAndCookies,
  ...props.headersAndCookies,
  ...(nextLocaleDetectionEnabled && {
    localeCookieName: nextLocaleCookieName,   // 'NEXT_LOCALE'
  }),
};

So it wins even when you set localeCookieName yourself. A reader configuring a custom cookie name currently has no way to tell from the docs that it is silently replaced. The callout documents that precedence and the localeDetection: false opt-out.

Verification

  • Behavior confirmed by reading packages/next/src/config.ts and packages/next/src/utils/cookies.ts upstream, not inferred from the changelog.
  • Callout type="info" matches the existing convention in this file.
  • validate:callouts (431 files), validate:structure, validate:reference-links (385 files), and validate-links all pass.

Context

Follow-up to #426, where I flagged this gap rather than expanding that PR's scope. Independent of #426 — no file overlap, so the two can merge in either order.

The headersAndCookies reference said every field defaults to the library's
standard name, which is now incomplete. Since gt-next@11.1.3
(generaltranslation/gt#2004), withGTConfig repoints localeCookieName at
NEXT_LOCALE whenever the Next.js config sets i18n and leaves localeDetection
enabled, so Pages Router locale persistence matches what the router reads.

The override is applied after props.headersAndCookies in the merge, so it wins
even when localeCookieName is set explicitly. That is the part worth calling
out: a reader configuring their own cookie name has no way to tell from the
current docs that it is silently replaced. Also documents the opt-out
(localeDetection: false).

Verified against packages/next/src/config.ts and utils/cookies.ts upstream.
Follow-up to #426, which flagged this gap.

Verified: validate:callouts, validate:structure, validate:reference-links, and
validate-links all pass.
@moss-bryophyta
moss-bryophyta enabled auto-merge (squash) July 30, 2026 00:52
@moss-bryophyta

Copy link
Copy Markdown
Contributor Author

Superseded by #430, which landed the same guidance in react/(frameworks)/nextjs/config.mdx (the NEXT_LOCALE preference-cookie override plus the v11.1.3 localeDetection: false escape hatch). Nothing unique left here, so closing instead of rebasing a redundant conflict.

auto-merge was automatically disabled July 30, 2026 17:21

Pull request was closed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant