Handling multi-language and region-specific URLs

[seosen-py]

Hi everyone!

I'm relatively new to MedusaJS and currently exploring how to implement multi-language support with region-specific URLs.

I'm a bit confused by the current approach to localization. Despite having a Translations feature, there doesn't seem to be a native concept of a default language out of the box. Moreover, I couldn't find a built-in mechanism to assign available languages to a specific region, other than relying on metadata (which feels more like a workaround rather than a scalable, production-ready solution).

Let's look at an example.

Say my client is running a store that operates primarily in Canada. Its default language is English (en-CA), with French (fr-CA) as a secondary option. At the same time, the store operates in France, offering both French (fr-FR) and English (en-FR).

For proper SEO and user experience, the URL structure would ideally look like this:

• / <= default region, default language (en-CA)

• /fr <= default region, French language (fr-CA)

• /en-fr <= France, English language

• /fr-fr <= France, French language

Shopify solved this nicely a while ago by introducing the "Markets" concept, where a Market ties together:

• Countries

• Currencies

• Taxes

• Shipping & Payment methods

• Available languages

And etc.

I know Medusa uses Regions for pricing, taxes, and shipping, but it seems to lack the language binding part.

Since I'm still getting familiar with Medusa, I might be missing something about how this is intended to be architected. After a couple of days of research, this is where I got stuck.

Has anyone successfully implemented a similar setup, or are there any plans to introduce a more unified "Market-like" abstraction in the core? I would really appreciate any guidance or best practices!

[arhxam]

Your reading is basically correct for current Medusa: locale support is store-wide, while a region models the commerce side of the problem. I don't see a built-in Region ↔ Locale relation or a Shopify-style Market aggregate today.

I would keep the two axes separate and add a small market layer in the storefront (or a custom module if non-developers must manage it):

const markets = {
  ca: {
    regionId: "reg_ca",
    countryCode: "ca",
    defaultLocale: "en-CA",
    locales: ["en-CA", "fr-CA"],
  },
  fr: {
    regionId: "reg_fr",
    countryCode: "fr",
    defaultLocale: "fr-FR",
    locales: ["fr-FR", "en-FR"],
  },
} as const

Then make URL resolution deterministic:

URL	Market	Locale
/	ca	en-CA
/fr	ca	fr-CA
/en-fr	fr	en-FR
/fr-fr	fr	fr-FR

For every request, resolve that tuple once and use it consistently:

• pass the region ID/country when fetching prices and creating or updating the cart;
• pass the locale with sdk.setLocale(...), the locale query parameter, or x-medusa-locale;
• set the cart locale too, so line-item content stays in the selected language;
• reject locale/market combinations that are not in the matrix;
• generate canonical and hreflang URLs from the same matrix, with / as x-default if that is your intended SEO policy.

This lines up with the current docs: StoreLocale belongs to the store and supported_locales is store-wide, localization is selected per Store API request, and region selection is separately used for prices and checkout.

For a fixed set of markets, a typed config is simpler and safer than metadata. If markets must be editable in Admin, I would promote the same shape to a custom Market data model linked to a region, rather than spreading the policy across region metadata. Either way, the default market/default locale is application policy, not something I would infer from array order.