feat(core): TRAC-421 consume merchant-configured locale subfolders from BC backend by mfaris9 · Pull Request #3015 · bigcommerce/catalyst

mfaris9 · 2026-05-18T02:11:04Z

What / Why

PROJECT-5002 added merchant-configurable per-locale URL subfolders in the BC Control Panel — e.g., fr-CA can be served at /fr/ instead of /fr-CA/. The Storefront GraphQL API exposes this as Locale.fullPath.

This PR teaches Catalyst to use that configured subfolder for URL routing, while keeping the locale code for translations, <html lang>, Accept-Language, and BC content negotiation.

JIRA

TRAC-421

Testing

Tested 5 cases in Integration.

Case 1 — No custom subfolders (legacy)

{locale = fr, isDefault=true, path=""}
{locale = es-es, isDefault=false, path=""}
{locale = es-mx, isDefault=false, path=""}
{locale = uk, isDefault=false, path=""}

Expected URLs:

site.com/ <-- fr locale
site.com/es-es/ <-- es-es locale
site.com/es-mx/ <-- es-mx locale
site.com/uk/ <-- uk locale

Tested: [X]

Case 2 — One non-default has a subfolder

{locale = fr, isDefault=true, path="" }
{locale = es-es, isDefault=false, path="es"}
{locale = es-mx, isDefault=false, path=""}
{locale = uk, isDefault=false, path=""}

Expected URLs:

site.com/ <-- fr locale
site.com/es/ <-- es-es locale
site.com/es-mx/ <-- es-mx locale
site.com/uk/ <-- uk locale

Tested: [X]

Case 3 — Default and one non-default have subfolders

{locale = fr, isDefault=true, path="fr" }
{locale = es-es, isDefault=false, path="es"}
{locale = es-mx, isDefault=false, path=""}
{locale = uk, isDefault=false, path=""}

Expected URLs:

site.com/fr/ <-- fr locale
site.com/es/ <-- es-es locale
site.com/es-mx/ <-- es-mx locale
site.com/uk/ <-- uk locale

Note: nobody lives at bare /. Hitting site.com/ redirects to site.com/fr/.

Tested: [X]

Case 4 — Every non-default has a subfolder, default blank

{locale = fr, isDefault=true, path="" }
{locale = es-es, isDefault=false, path="es"}
{locale = es-mx, isDefault=false, path="mx"}
{locale = uk, isDefault=false, path="uk"}

Expected URLs:

site.com/ <-- fr locale
site.com/es/ <-- es-es locale
site.com/mx/ <-- es-mx locale
site.com/uk/ <-- uk locale

Tested: [X]

Case 5 — Default has a path, one non-default left blank

{locale = fr, isDefault=true, path="fr" }
{locale = es-es, isDefault=false, path="es"}
{locale = es-mx, isDefault=false, path="ex-mx"}
{locale = uk, isDefault=false, path=""}

Expected URLs:

site.com/fr/ <-- fr locale
site.com/es/ <-- es-mx locale
site.com/es-mx/ <-- es-mx locale
site.com/ <-- uk locale

Tested: [X]

Migration

None needed.

changeset-bot · 2026-05-18T02:11:08Z

🦋 Changeset detected

Latest commit: 9987270

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	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

vercel · 2026-05-18T02:11:09Z

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

Project	Deployment	Actions	Updated (UTC)
catalyst	Error		May 26, 2026 3:46pm

github-actions · 2026-05-18T02:20:01Z

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	83	88

Category Scores

Category	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Performance	77	92	65	85
Accessibility	95	92	100	100
Best Practices	100	100	95	95
SEO	88	100	71	71

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	3.5 s	3.2 s	3.7 s	3.7 s
CLS	0	0	0	0
FCP	1.2 s	1.1 s	2.7 s	2.7 s
TBT	0 ms	10 ms	0 ms	0 ms
Max Potential FID	40 ms	60 ms	50 ms	30 ms
Time to Interactive	3.6 s	3.9 s	3.7 s	3.7 s

Full Unlighthouse report →

github-actions · 2026-05-18T02:35:02Z

Bundle Size Report

Comparing against baseline from 7b38d98 (2026-05-20).

No bundle size changes detected.

mfaris9 · 2026-05-18T03:46:20Z

Question: since fullPath is removed from the schema entirely when the availableLocaleFullPathEnabled flag is off, I went with a try/catch fallback to a legacy query. I am open to suggestions if there's a cleaner way to do this.

funivan · 2026-05-18T10:18:52Z


 const localeNodes = buildConfig.get('locales');

+function pathFromFullPath(fullPath: string | null | undefined): string | undefined {


We can output also path if needed, this is an easy task.

store { locales{ code : 'fr' isDefault : true path: 'france' fullPath : 'site.com/france' } }

That would be great, it would be cleaner to have the path output as well

parthshahp · 2026-05-18T15:35:00Z

+  return parsed.data.graphqlErrors.some((e) => e.message.includes("Cannot query field 'fullPath'"));
+}
+
+async function fetchSettings() {


Is this the standard pattern for new GQL schemas in storefront? I would double check if we can just change the schema without the flag, it should just return null anyway. May not be possible.

I didn't love this change either because we'll have to go back and clean it up once the flag graduates... BC's storefront removes from the schema entirely when the flag is off. I agree it feels weird and I feel as though this issue probably comes up often i'll send a message in trac-team to see if anyone else handled this differently.

Hey Parth, looks like this is standard pattern on the storefront side (see SearchSchema.scala:28). Thanks for the review.

parthshahp · 2026-05-18T15:41:32Z

-import { defaultLocale, locales } from './locales';
-
-enum LocalePrefixes {
-  ALWAYS = 'always',


Just curious: why did we remove this?

I didn't think we needed the enum anymore as we are only using as-needed. I can add a comment like this if you prefer:

localePrefix: {
// 'as-needed' removes the prefix for the default locale.
// 'always' would prefix every locale including the default.
// 'never' has cache-related issues — avoid:
// amannn/next-intl#786
mode: 'as-needed',
prefixes,
}

Enum change reverted to provide context for merchant configuration

…om BC backend

mfaris9 requested a review from a team as a code owner May 18, 2026 02:11

vercel Bot deployed to Preview May 18, 2026 02:34 View deployment

mfaris9 marked this pull request as draft May 18, 2026 03:12

vercel Bot deployed to Preview May 18, 2026 03:32 View deployment

mfaris9 marked this pull request as ready for review May 18, 2026 03:43

funivan reviewed May 18, 2026

View reviewed changes

parthshahp reviewed May 18, 2026

View reviewed changes

vercel Bot deployed to Preview May 18, 2026 18:15 View deployment

vercel Bot deployed to Preview May 20, 2026 14:37 View deployment

mfaris9 marked this pull request as draft May 20, 2026 15:13

vercel Bot had a problem deploying to Preview May 20, 2026 15:41 Failure

vercel Bot had a problem deploying to Preview May 22, 2026 19:39 Failure

mfaris9 force-pushed the TRAC-421 branch from 4b3e5e6 to 748d998 Compare May 22, 2026 19:45

vercel Bot had a problem deploying to Preview May 22, 2026 19:45 Failure

funivan mentioned this pull request May 25, 2026

feat(core): TRAC-282 support empty and custom locale subfolders #3023

Closed

2 tasks

mfaris9 force-pushed the TRAC-421 branch from 748d998 to d315c95 Compare May 26, 2026 15:35

vercel Bot had a problem deploying to Preview May 26, 2026 15:35 Failure

feat(core): TRAC-421 consume merchant-configured locale subfolders fr…

9987270

…om BC backend

mfaris9 force-pushed the TRAC-421 branch from d315c95 to 9987270 Compare May 26, 2026 15:46

vercel Bot had a problem deploying to Preview May 26, 2026 15:46 Failure


		const localeNodes = buildConfig.get('locales');

		function pathFromFullPath(fullPath: string \| null \| undefined): string \| undefined {

Conversation

mfaris9 commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What / Why

JIRA

Testing

Migration

Uh oh!

changeset-bot Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlighthouse Performance Comparison — Vercel

Summary Score

Category Scores

Core Web Vitals

Uh oh!

github-actions Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Report

Uh oh!

mfaris9 commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mfaris9 commented May 18, 2026 •

edited

Loading

changeset-bot Bot commented May 18, 2026 •

edited

Loading

vercel Bot commented May 18, 2026 •

edited

Loading

github-actions Bot commented May 18, 2026 •

edited

Loading

github-actions Bot commented May 18, 2026 •

edited

Loading

mfaris9 commented May 18, 2026 •

edited

Loading