Serve Translations in the Storefront

In this guide, you’ll learn how to use locales and serve translated content in your storefront application in your Medusa application.

Fetch Store Locales#

You can retrieve the list of locales available in 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, to fetch the list of locales, send a GET request to the following endpoint:

Code
1curl "http://localhost:9000/store/locales" \2-H 'x-publishable-api-key: {your_publishable_api_key}'

Learn more in the Localization storefront guide.

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.

Medusa determines the locale for the request in the following order of priority:

• The locale query parameter in the API request.
• The x-medusa-locale header in the API request.

If translations aren't available for the selected locale, or no locale is selected, the original content stored in the resource's data model is returned.

For example:

Code
1curl "http://localhost:9000/store/products?locale=fr-FR" \2-H 'x-publishable-api-key: {your_publishable_api_key}'

This returns the list of products with their French (France) translations if available:

Code
1{2  "products": [3    {4      "id": "prod_123",5      "title": "Produit Exemple",6      "description": "Ceci est une description en français.",7      // other product fields...8    },9    // other products...10  ]11}

Learn more in the List Products storefront guide.

Set a Cart's Locale#

A cart can have a locale, which determines the language of the item contents. You can set the locale when creating the cart and update it if the user changes their language preference.

For example, when creating a cart, set the locale property in the request body:

Code
1curl -X POST "http://localhost:9000/store/carts" \2-H 'x-publishable-api-key: {your_publishable_api_key}' \3-H "Content-Type: application/json" \4-d '{5  // other cart properties...6  "locale": "fr-FR"7}'

This creates a cart with the French (France) locale. When you add items to the cart, their titles and descriptions are displayed in French if translations are available.

If you don't specify a locale when creating the cart, the original product content is used for the items in the cart.

Learn more in the Create Cart and Update Cart storefront guides.

Locale of Placed Order#

When a cart is completed and an order is placed, the locale of the cart is copied to the order. The content of items in the order is displayed in the locale that was set in the cart.

This ensures that customers see order details in their preferred language.