fix: locale switcher correctly works w/ localized Makeswift paths

[agurtovoy]

What/Why?

Fix locale switcher on localized Makeswift pages with different paths.

Testing

Kapture.2025-09-23.at.16.16.32.mp4

Migration

N/A

[changeset-bot]

🦋 Changeset detected

Latest commit: eb2d4e1

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-makeswift	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	Preview	Comments	Updated (UTC)
catalyst-b2b	Ready	Preview	Comment	Sep 24, 2025 3:38pm
catalyst-canary	Ready	Preview	Comment	Sep 24, 2025 3:38pm

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
catalyst	Ignored			Sep 24, 2025 3:38pm
catalyst-uk	Ignored			Sep 24, 2025 3:38pm

[agurtovoy]

The canonical way to handle this in next-intl is to use the pathnames configuration, but it's too inflexible for our purposes here:

• If we kept it as a build-time configuration, it would require a site redeploy after each Makeswift publish that updates page paths.
• A build-time configuration would also be incorrect for previews.
• If we converted it into a run-time configuration, we’d have to rework our code to retrieve the derived navigation components from a context and then cache and revalidate them at runtime.

The approach in this PR is more localized and arguably more performant, as we don't have to retrieve the whole sitemap.

[migueloller]

Thanks @agurtovoy!

[migueloller]

My understanding is that route changes already trigger transitions. I'm curious why we're using it here.

Perhaps instead we meant to do this:

return useCallback(startTransition(async () => {
  const localizedPathname = await getLocalizedPathname({})

  router.push()
}))

Note how the async transition will mark the transition as pending when the action itself is triggered. This pattern is actually what a "React Action" is, by definition.

[agurtovoy]

There is already a top-level startTransition call wrapping this callback here; the nested startTransition call follows the pattern explicitly set out for async transitions here: https://react.dev/reference/react/useTransition#react-doesnt-treat-my-state-update-after-await-as-a-transition.

That said, I didn't know that using router.push guarantees a startTransition call, which does make the explicit startTransition call unnecessary.

[agurtovoy]

Added a clarifying comment.

[migueloller]

Ah, TIL. Thanks!

[migueloller]

A separate thought is: should the transition be handles outside of the hook, where it's not known whether there's a state update, or should it be handled inside as in my suggestion comment, so that the state update and transition are colocated 🤔

[agurtovoy]

I don't think there's a significant semantic difference in this case; you could argue it either way. I originally left it out of this particular hook and kept it in the LocaleSwitcher because, conceptually, switching the locale involves navigation, and that should be a transition, regardless of how the navigation is triggered.

[agurtovoy]

You could argue that because switching the locale involves navigation, the hook should encapsulate that and return the pending state together with the switchLocale callback. I'm sympathetic to that argument, but not enough to go rework this, haha.

[migueloller]

Yeah, I would argue the latter. And also, APIs like router.push encapsulate the transition as well.

That said, I'm not expecting you to rework this. Thanks for the fix!

[agurtovoy]

APIs like router.push encapsulate the transition as well.

But it doesn't return a pending state, so you have to wrap it in a startTransition call if you want that anyway. Similarly, the useSwitchLocale hook doesn't return a pending state because it was conceived as a lower-level primitive, and the pending state handling was left to the LocaleSwitcher component itself.

Now, if it occurred to me at the time, I'd likely go with the design you're advocating, I'm just pointing out that either of them is reasonable.