TRAC-1298: Update locale paths to runtime resolution

[jordanarldt]

What/Why?

Custom locale subfolders (/fr-fr, /es-es) didn't resolve consistently. The table was snapshotted into build-config.json at build time, so incomplete data during next build 404'd every localized URL until the next deploy — and next-intl treats a custom subfolder as a replacement for the bare locale code, not an alias, so there was no fallback.

Locale config is now fetched at runtime and is the only source. withIntl resolves it once per request (KV-cached, SWR, 5 min) and forwards it to the render via x-bc-locale-routing, so outbound URLs match what resolved the inbound one. No build-time fallback was kept — it would silently serve the stale URL space this fixes. A warm cache rides out an outage; only a cold cache plus an unreachable API fails, returning 503 rather than a 404.

Worth a look:

• redirect/permanentRedirect moved to ~/i18n/navigation-server and are now async — they can't stay in ~/i18n/routing, which is in the client graph where next/headers fails the build.
• ~/i18n/locales is removed. i18n/request.ts reads the forwarded header only; fetching there would recurse via client.fetch → getLocale().
• generateStaticParams removed from app/[locale]/layout.tsx. Route modes in the build are unchanged.
• Also fixes /xmlsitemap.php, which resolved to /<locale>/sitemap.xml — a 404, since /sitemap.xml is excluded from the proxy.

Locale detection is unchanged.

Testing

pnpm build && pnpm start, then:

1. Each locale's URL loads, with matching links/canonical/hreflang. /xmlsitemap.php lands on /sitemap.xml.
2. Accept-Language: de on / redirects to German; switching locale in the header sticks on reload.
3. Change a subfolder in the control panel and restart — the new path resolves with no rebuild. This is the original bug.

Plus tests/ui/e2e/locale-switcher.spec.ts.

Migration

redirect/permanentRedirect move, and must be awaited:

-import { redirect } from '~/i18n/routing';
+import { redirect } from '~/i18n/navigation-server';

-  redirect({ href: '/login', locale });
+  await redirect({ href: '/login', locale });

~/i18n/locales is gone — use getLocaleRouting() from ~/i18n/locale-config. Link, useRouter and usePathname keep their ~/i18n/routing import.

If you map locales to channels in channels.config.ts: sitemap, robots and favicon now resolve the default channel directly, as they run outside the proxy.

[changeset-bot]

🦋 Changeset detected

Latest commit: c4976fa

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

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-core	Patch

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview	Aug 13, 2026 3:06pm

[github-actions]

Bundle Size Report

Comparing against baseline from 0c49112 (2026-08-13).

Metric	Baseline	Current	Delta
Total JS	449.3 kB	449.6 kB	+0.3 kB (+0.1%)

Per-Route First Load JS

Route	Baseline	Current	Delta
/maintenance/page	316.4 kB	316.6 kB	+0.2 kB (+0.1%)

Threshold: 5% increase. Routes with ⚠️ exceed the threshold.

[github-actions]

Unlighthouse Performance Comparison — Vercel

Comparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores.

Summary Score

Aggregate score across all categories as reported by Unlighthouse.

	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Score	90	93	92	95

Category Scores

Category	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Performance	69	78	75	79
Accessibility	95	98	95	92
Best Practices	100	100	100	100
SEO	88	86	100	100

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	5.2 s	4.1 s	3.7 s	5.3 s
CLS	0.039	0.183	0.001	0
FCP	1.2 s	1.2 s	1.2 s	1.2 s
TBT	0 ms	0 ms	0 ms	0 ms
Max Potential FID	30 ms	50 ms	50 ms	50 ms
Time to Interactive	5.2 s	4.2 s	3.7 s	5.4 s

Full Unlighthouse report →