From aa289dc94d7b7133deeb784df8d07323d6728416 Mon Sep 17 00:00:00 2001 From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com> Date: Fri, 31 Jul 2026 06:26:21 -0700 Subject: [PATCH] docs(react): document the Pages Router i18n config mismatch warning gt-next@11.1.4 (gt#2005) warns at build time when next.config i18n locale settings disagree with gt.config.json. Both Pages Router pages already import from gt.config.json; explain why that pattern matters and name the warning users see if the values drift. --- .../en-US/react/(frameworks)/nextjs/pages-router-middleware.mdx | 2 ++ docs/en-US/react/nextjs-pages-router-quickstart.mdx | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/en-US/react/(frameworks)/nextjs/pages-router-middleware.mdx b/docs/en-US/react/(frameworks)/nextjs/pages-router-middleware.mdx index a4316eaae..2c769548f 100644 --- a/docs/en-US/react/(frameworks)/nextjs/pages-router-middleware.mdx +++ b/docs/en-US/react/(frameworks)/nextjs/pages-router-middleware.mdx @@ -40,6 +40,8 @@ export default withGTConfig(nextConfig); Next.js serves the default locale without a prefix and prefixes the others. For example, English uses `/about` and French uses `/fr/about`. +Importing the values keeps both configurations in sync. If you hardcode `i18n.locales` or `i18n.defaultLocale` to values that differ from `gt.config.json`, `gt-next` prints a build-time warning that Next.js internationalized routing does not match the GT config file, because Next.js can then route to a locale that GT is not configured to translate. The comparison ignores ordering, so only the set of locales matters. + Keep each page at the root of `pages`; do not add a `[locale]` segment: diff --git a/docs/en-US/react/nextjs-pages-router-quickstart.mdx b/docs/en-US/react/nextjs-pages-router-quickstart.mdx index 9a71b4fa9..0f469143b 100644 --- a/docs/en-US/react/nextjs-pages-router-quickstart.mdx +++ b/docs/en-US/react/nextjs-pages-router-quickstart.mdx @@ -105,7 +105,7 @@ const nextConfig: NextConfig = { export default withGTConfig(nextConfig); ``` -Next.js keeps the default locale at `/` and prefixes the other locales, such as `/es` and `/fr`. You do not need `gt-next` middleware or a `pages/[locale]` route segment. See [Pages Router locale routing](/docs/react/nextjs/pages-router-middleware) for detection and migration details. +Next.js keeps the default locale at `/` and prefixes the other locales, such as `/es` and `/fr`. You do not need `gt-next` middleware or a `pages/[locale]` route segment. Import the values from `gt.config.json` rather than repeating them, so the two configurations cannot drift; `gt-next` warns at build time when they disagree. See [Pages Router locale routing](/docs/react/nextjs/pages-router-middleware) for detection and migration details. ### 4. Add a load function for local translations