4.6.14. Localization in API Routes

In this chapter, you'll learn how to handle localization in API routes of your Medusa application to serve content in different languages.

Overview#

Localization in API routes allows you to serve translated content based on the user's preferred language. The Medusa application provides built-in support for handling locale information in API requests and retrieving localized data.

When a locale is specified in a request, you can use it to retrieve translated versions of your data models' fields, providing a seamless multilingual experience for your users.

Learn more about translation, how to manage translations, and how to translate custom data models in the Translation Module documentation.

Routes with Localization Enabled by Default#

The Medusa application automatically applies the applyLocale middleware to all routes under the /store prefix. This makes req.locale available in every store route handler, and it allows your custom store routes to read the locale without additional middleware configuration.

However, applying the locale middleware does not mean every route translates its response automatically. Translation only happens when the route handler (or an underlying helper) resolves the locale and retrieves the appropriate translations. In Medusa's built-in store routes, translation is applied to the following routes:

• /store/products and /store/products/:id: product fields such as title and description
• /store/product-variants and /store/product-variants/:id: product variant fields

Other built-in store routes (including /store/carts/:id, /store/customers/me, and /store/orders/:id) receive the locale header but do not retrieve the translated content. Fields on data models reached through those routes, including custom models linked to their records, are returned untranslated even when x-medusa-locale is set.

Refer to the Translation Module documentation for a list of supported core data models with localization support.

Apply Localization to Custom Routes#

If you're creating custom API routes outside the /store prefix, you must manually apply the applyLocale middleware to enable localization support.

To apply the applyLocale middleware to all HTTP methods for a route, add it to the src/api/middlewares.ts file:

src/api/middlewares.ts
1import { applyLocale, defineMiddlewares } from "@medusajs/framework/http"2
3export default defineMiddlewares({4  routes: [5    {6      matcher: "/custom*",7      middlewares: [applyLocale],8    },9  ],10})

This applies the applyLocale middleware to all routes matching /custom*, regardless of the HTTP method.

Alternatively, you can apply the middleware only to specific HTTP methods using the method property:

src/api/middlewares.ts
1import { applyLocale, defineMiddlewares } from "@medusajs/framework/http"2
3export default defineMiddlewares({4  routes: [5    {6      matcher: "/custom*",7      method: ["GET"],8      middlewares: [applyLocale],9    },10  ],11})

How to Pass Locale in API Requests#

You can pass the locale in API requests to routes that support localization using either of the following methods:

1. The locale query parameter
2. The x-medusa-locale request header

The query parameter takes priority over the header if both are provided.

The locale must follow the IETF BCP 47 standard, such as en-US for English (United States) or fr-FR for French (France).

For example:

The above examples retrieve products with their fields translated to French (France) if translations are available. If no translations exist for the requested locale, the original content stored in the data model is returned.

Access Request Locale in API Routes#

After applying the applyLocale middleware, you can access the request's locale from the locale property of the MedusaRequest object.

For example:

src/api/custom/route.ts
1import type {2  MedusaRequest,3  MedusaResponse,4} from "@medusajs/framework/http"5
6export const GET = async (7  req: MedusaRequest,8  res: MedusaResponse9) => {10  const locale = req.locale11
12  // use locale to retrieve localized data...13}

The req.locale property contains the locale value from either the query parameter or the request header. If no locale is specified in the request, req.locale is undefined.

Retrieve Localized Data with Query#

To retrieve data models with translated fields, pass the locale property in the second parameter object of Query when querying your data.

For example, to retrieve products with translated names and descriptions:

src/api/store/products/route.ts
1import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"2import {3  ContainerRegistrationKeys,4} from "@medusajs/framework/utils"5
6export const GET = async (req: MedusaRequest, res: MedusaResponse) => {7  const query = req.scope.resolve(8    ContainerRegistrationKeys.QUERY9  )10
11  const { data: products } = await query.graph(12    {13      entity: "product",14      fields: ["id", "title", "description"],15    },16    {17      locale: req.locale,18    }19  )20
21  res.json({ products })22}

In this example, the products are retrieved with their title and description fields translated to the locale specified in the request.

Learn more in the Query chapter.

Retrieve Localized Data for Custom Models#

You can also retrieve localized data for custom data models. Learn more in the Translate Custom Data Models guide.