Storefront Localization

In this guide, you'll learn how to support multiple languages and locales in your storefront.

Overview#

Medusa provides localization features through the Translation Module. The Translation Module allows you to manage locales and translations for various resources in your store, such as products and categories.

Admin users can specify supported locales, and add translations for different resources from the Medusa Admin. Then, you can allow customers to choose their locale and show them translated content in your storefront.

Refer to the Translation Module documentation to learn more about translation concepts and features. This guide focuses on how to serve localized content in your storefront.

Retrieve Supported Locales#

You can retrieve the list of locales supported by your store using the List Locales Store API route. You can display this list to customers, allowing them to select their preferred language.

For example:

The response has a locales field, which is an array of locales.

Each locale has a code property that follows the IETF BCP 47 standard. For example, en-US represents American English, while fr-FR represents French (France).

Retrieve Translations for Resources#

Currently, you can retrieve translations using the Store API routes for product-related resources, such as products, product variants, and categories. Future releases will expand translation support to additional resources.

By default, Medusa serves the original content of a resource. You can override the locale for a request to get the translated content if available.

Set Locale in JS SDK#

The JS SDK has a setLocale method that you can use to set the locale for subsequent requests.

The JS SDK will automatically include the x-medusa-locale header in API requests. Also, if your application supports localStorage, the method sets the locale in the medusa_locale key of the localStorage.

For example, when a customer selects a locale in your storefront, you can set the locale in the JS SDK:

Code
1sdk.setLocale("fr-FR")2// products content is fetched in French3const { products } = await sdk.store.product.list()

In the above example, you set the locale to French using the setLocale method. It accepts the locale string in the IETF BCP 47 standard.

When you fetch the products, their content, such as title and description, is in French and falls back to the original content if translations aren't available.

You can also retrieve the currently set locale using the getLocale method:

Code
1const currentLocale = sdk.getLocale()2console.log(currentLocale) // "fr-FR"

Set Locale without JS SDK#

If you're sending requests to the Store API without using the JS SDK, you can set the locale using either the locale query parameter or the x-medusa-locale header.

Learn more in the Store API reference.

Set Locale in Server Environments#

If you're making Store API requests from a server environment (such as server components or server actions in Next.js), you can use cookies to persist the selected locale across requests.

When a customer selects a locale in your storefront, set a cookie (for example, _medusa_locale) with the selected locale value:

Code
1import { cookies } from "next/headers"2
3export const setLocale = async (locale: string) => {4  const cookies_ = await cookies()5  cookies_.set("_medusa_locale", locale, {6    maxAge: 60 * 60 * 24 * 7,7  })8}

Then, create a utility that returns the locale from the cookie as a x-medusa-locale header:

Code
1import { cookies } from "next/headers"2
3export const getLocaleHeader = async () => {4  try {5    const cookies_ = await cookies()6    const locale = cookies_.get("_medusa_locale")?.value7
8    return { "x-medusa-locale": locale }9  } catch {10    return {}11  }12}

Finally, use the utility to set the x-medusa-locale header in your Store API requests:

Code
1import { getLocaleHeader } from "@/lib/locale"2
3export async function listProducts() {4  const headers = {5    ...(await getLocaleHeader()),6  }7
8  return sdk.store.product.list({}, { headers })9}

Retrieve Translated Products#

When you pass the locale while fetching products, their content will be in the specified locale if translations are available. Learn more in the List Products guide.

Set Cart's Locale#

When creating a cart, you should set the cart's locale to ensure that item contents are in the correct language. You can also update the cart's locale later if the customer changes their language preference.

Learn more in the Create Cart and Update Cart guides.