chore: generate and update OAS for translations (#14281)

* chore: generate and update OAS for translations

* support localization header

* add locale to all store routes

* fixes

* small fix

www/utils/packages/docs-generator/src/classes/kinds/oas.ts

@@ -135,6 +135,7 @@ class OasKindGenerator extends FunctionKindGenerator {
     },
   ]
   readonly RESPONSE_TYPE_NAMES = ["MedusaResponse"]
+  readonly LOCALIZED_ROUTES = ["store/"]
 
   /**
    * This map collects tags of all the generated OAS, then, once the generation process finishes,
@@ -348,6 +349,7 @@ class OasKindGenerator extends FunctionKindGenerator {
       node,
       tagName,
       methodName,
+      oasPath,
     })
 
     oas.parameters?.push(...queryParameters)
@@ -582,6 +584,7 @@ class OasKindGenerator extends FunctionKindGenerator {
       node,
       tagName,
       methodName,
+      oasPath,
       forUpdate: true,
     })
 
@@ -1170,6 +1173,7 @@ class OasKindGenerator extends FunctionKindGenerator {
     node,
     tagName,
     methodName,
+    oasPath,
     forUpdate = false,
   }: {
     /**
@@ -1184,6 +1188,10 @@ class OasKindGenerator extends FunctionKindGenerator {
      * The tag's name.
      */
     tagName?: string
+    /**
+     * The OAS path.
+     */
+    oasPath: string
     /**
      * Whether the request parameters are retrieved for update purposes only.
      */
@@ -1200,6 +1208,30 @@ class OasKindGenerator extends FunctionKindGenerator {
   } {
     const queryParameters: OpenAPIV3.ParameterObject[] = []
     let requestSchema: OpenApiSchema | undefined
+    const isLocalizedRoute = this.LOCALIZED_ROUTES.some((route) =>
+      oasPath.startsWith(route)
+    )
+
+    if (isLocalizedRoute) {
+      queryParameters.push(
+        this.getParameterObject({
+          type: "query",
+          name: "locale",
+          description:
+            "The locale in BCP 47 format to retrieve localized content.",
+          required: false,
+          schema: {
+            type: "string",
+            example: "en-US",
+            externalDocs: {
+              url: "https://docs.medusajs.com/resources/commerce-modules/translation/storefront",
+              description:
+                "Learn more in the Serve Translations in Storefront guide.",
+            },
+          },
+        })
+      )
+    }
 
     if (
       !node.parameters[0].type ||
@@ -1343,6 +1375,22 @@ class OasKindGenerator extends FunctionKindGenerator {
           },
         },
       }),
+      this.getParameterObject({
+        type: "header",
+        name: "Content-Language",
+        description:
+          "The locale in BCP 47 format to retrieve localized content.",
+        required: false,
+        schema: {
+          type: "string",
+          example: "en-US",
+          externalDocs: {
+            url: "https://docs.medusajs.com/resources/commerce-modules/translation/storefront",
+            description:
+              "Learn more in the Serve Translations in Storefront guide.",
+          },
+        },
+      }),
     ]
   }