Skip to content

page.mdx

Latest commit

 

History

History
225 lines (153 loc) · 7.96 KB

page.mdx

File metadata and controls

225 lines (153 loc) · 7.96 KB
Raw

import { CodeTabs, CodeTab, Prerequisites } from "docs-ui"

export const metadata = { title: ${pageNumber} Localization in API Routes, keywords: ["translation api-routes"] }

{metadata.title}

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

<Prerequisites items={[ { text: "Medusa v2.12.4 or later", link: "https://github.com/medusajs/medusa/releases/tag/v2.12.4" }, { text: "Translation Module Configured", link: "!resources!/commerce-modules/translation#configure-translation-module", }, ]} />

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.

If you need translated fields on a model that is fetched through a non-translating route (for example, a custom model linked to a cart or order), create a custom store route that queries the model directly and applies the translations.

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:

export const allMethodsHighlights = [ ["7", "applyLocale", "Apply the middleware to the route"], ]

import { applyLocale, defineMiddlewares } from "@medusajs/framework/http"

export default defineMiddlewares({
  routes: [
    {
      matcher: "/custom*",
      middlewares: [applyLocale],
    },
  ],
})

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:

export const specificMethodHighlights = [ ["7", "method", "Apply the middleware only to GET requests"], ]

import { applyLocale, defineMiddlewares } from "@medusajs/framework/http"

export default defineMiddlewares({
  routes: [
    {
      matcher: "/custom*",
      method: ["GET"],
      middlewares: [applyLocale],
    },
  ],
})

Learn more about middlewares in the Middlewares chapter.

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).

Refer to the JS SDK reference for details on how to pass locale.

For example:

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

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.

Store API routes require a publishable API key in the request header. Learn more in the Store API reference.

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:

export const accessLocaleHighlights = [ ["10", "req.locale", "Access the request's locale"], ]

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

export const GET = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  const locale = req.locale

  // use locale to retrieve localized data...
}

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:

export const queryHighlights = [ ["17", "locale", "Pass the request locale to retrieve localized data"], ]

import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import {
  ContainerRegistrationKeys,
} from "@medusajs/framework/utils"

export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
  const query = req.scope.resolve(
    ContainerRegistrationKeys.QUERY
  )

  const { data: products } = await query.graph(
    {
      entity: "product",
      fields: ["id", "title", "description"],
    },
    {
      locale: req.locale,
    }
  )

  res.json({ products })
}

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.