From c8a7122ba918751b215dc0b19cf9b09b2c011ab8 Mon Sep 17 00:00:00 2001
From: Adrien de Peretti <adrien.deperetti@gmail.com>
Date: Tue, 16 Dec 2025 10:39:40 +0100
Subject: [PATCH] chore(): Update locale header usage (#14318)

* chore(): Update locale header usage

* Create three-kiwis-shave.md

* chore(): Update locale header usage
---
 .changeset/three-kiwis-shave.md                        |  6 ++++++
 .../framework/src/http/__tests__/apply-locale.spec.ts  | 10 +++++-----
 .../framework/src/http/middlewares/apply-locale.ts     |  6 +++---
 packages/core/framework/src/http/types.ts              |  2 +-
 packages/core/js-sdk/src/client.ts                     |  2 +-
 5 files changed, 16 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/three-kiwis-shave.md

diff --git a/.changeset/three-kiwis-shave.md b/.changeset/three-kiwis-shave.md
new file mode 100644
index 0000000000..fe35ef20c2
--- /dev/null
+++ b/.changeset/three-kiwis-shave.md
@@ -0,0 +1,6 @@
+---
+"@medusajs/framework": patch
+"@medusajs/js-sdk": patch
+---
+
+chore(): Update locale header usage
diff --git a/packages/core/framework/src/http/__tests__/apply-locale.spec.ts b/packages/core/framework/src/http/__tests__/apply-locale.spec.ts
index 9b260f067d..d7669054f1 100644
--- a/packages/core/framework/src/http/__tests__/apply-locale.spec.ts
+++ b/packages/core/framework/src/http/__tests__/apply-locale.spec.ts
@@ -36,10 +36,10 @@ describe("applyLocale", () => {
     expect(nextFunction).toHaveBeenCalledTimes(1)
   })
 
-  it("should set locale from Content-Language header when query param is not present", async () => {
+  it("should set locale from x-medusa-locale header when query param is not present", async () => {
     mockRequest.query = {}
     ;(mockRequest.get as jest.Mock).mockImplementation((header: string) => {
-      if (header === "content-language") {
+      if (header === "x-medusa-locale") {
         return "fr-FR"
       }
       return undefined
@@ -51,10 +51,10 @@ describe("applyLocale", () => {
     expect(nextFunction).toHaveBeenCalledTimes(1)
   })
 
-  it("should prioritize query parameter over Content-Language header", async () => {
+  it("should prioritize query parameter over x-medusa-locale header", async () => {
     mockRequest.query = { locale: "de-DE" }
     ;(mockRequest.get as jest.Mock).mockImplementation((header: string) => {
-      if (header === "content-language") {
+      if (header === "x-medusa-locale") {
         return "fr-FR"
       }
       return undefined
@@ -80,7 +80,7 @@ describe("applyLocale", () => {
   it("should handle empty string in query parameter", async () => {
     mockRequest.query = { locale: "" }
     ;(mockRequest.get as jest.Mock).mockImplementation((header: string) => {
-      if (header === "content-language") {
+      if (header === "x-medusa-locale") {
         return "es-ES"
       }
       return undefined
diff --git a/packages/core/framework/src/http/middlewares/apply-locale.ts b/packages/core/framework/src/http/middlewares/apply-locale.ts
index b08004fec4..5acecbc452 100644
--- a/packages/core/framework/src/http/middlewares/apply-locale.ts
+++ b/packages/core/framework/src/http/middlewares/apply-locale.ts
@@ -5,14 +5,14 @@ import type {
   MedusaResponse,
 } from "../types"
 
-const CONTENT_LANGUAGE_HEADER = "content-language"
+const CONTENT_LANGUAGE_HEADER = "x-medusa-locale"
 
 /**
  * Middleware that resolves the locale for the current request.
  *
  * Resolution order:
  * 1. Query parameter `?locale=en-US`
- * 2. Content-Language header
+ * 2. x-medusa-locale header
  *
  * The resolved locale is set on `req.locale`.
  */
@@ -29,7 +29,7 @@ export async function applyLocale(
     return next()
   }
 
-  // 2. Check Content-Language header
+  // 2. Check x-medusa-locale header
   const headerLocale = req.get(CONTENT_LANGUAGE_HEADER)
   if (headerLocale) {
     req.locale = normalizeLocale(headerLocale)
diff --git a/packages/core/framework/src/http/types.ts b/packages/core/framework/src/http/types.ts
index 64f952b627..3b34fd9161 100644
--- a/packages/core/framework/src/http/types.ts
+++ b/packages/core/framework/src/http/types.ts
@@ -187,7 +187,7 @@ export interface MedusaRequest<
   /**
    * The locale for the current request, resolved from:
    * 1. Query parameter `?locale=`
-   * 2. Content-Language header
+   * 2. x-medusa-locale header
    * 3. Store's default locale
    */
   locale?: string
diff --git a/packages/core/js-sdk/src/client.ts b/packages/core/js-sdk/src/client.ts
index cf88500755..6732214988 100644
--- a/packages/core/js-sdk/src/client.ts
+++ b/packages/core/js-sdk/src/client.ts
@@ -250,7 +250,7 @@ export class Client {
       // We always want to fetch the up-to-date JWT token before firing off a request.
       const headers = new Headers(defaultHeaders)
       const customHeaders = {
-        "content-language": this.locale,
+        "x-medusa-locale": this.locale,
         ...this.config.globalHeaders,
         ...(await this.getJwtHeader_()),
         ...init?.headers,