chore: TSDocs for Translation Module (#14280)

* tsdocs for translation module

* fixes

packages/core/core-flows/src/translation/steps/create-translations.ts

@@ -5,9 +5,17 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The translations to create.
+ */
+export type CreateTranslationsStepInput = CreateTranslationDTO[]
+
 export const createTranslationsStepId = "create-translations"
 /**
  * This step creates one or more translations.
+ * 
+ * @since 2.12.3
+ * @featureFlag translation
  *
  * @example
  * const data = createTranslationsStep([
@@ -21,7 +29,7 @@ export const createTranslationsStepId = "create-translations"
  */
 export const createTranslationsStep = createStep(
   createTranslationsStepId,
-  async (data: CreateTranslationDTO[], { container }) => {
+  async (data: CreateTranslationsStepInput, { container }) => {
     const service = container.resolve<ITranslationModuleService>(
       Modules.TRANSLATION
     )

packages/core/core-flows/src/translation/steps/delete-translations.ts

@@ -10,6 +10,15 @@ export type DeleteTranslationsStepInput = string[]
 export const deleteTranslationsStepId = "delete-translations"
 /**
  * This step deletes one or more translations.
+ * 
+ * @since 2.12.3
+ * @featureFlag translation
+ *
+ * @example
+ * const data = deleteTranslationsStep([
+ *   "trans_123",
+ *   "trans_456",
+ * ])
  */
 export const deleteTranslationsStep = createStep(
   deleteTranslationsStepId,

packages/core/core-flows/src/translation/steps/update-translations.ts

@@ -26,14 +26,33 @@ export type UpdateTranslationsStepInput =
       update: UpdateTranslationDataDTO
     }
   | {
+    /**
+     * The translations to update by ID.
+     */
       translations: UpdateTranslationDTO[]
     }
 
 export const updateTranslationsStepId = "update-translations"
 /**
- * This step updates translations matching the specified filters.
+ * This step updates translations matching the specified filters or by ID.
+ * 
+ * @since 2.12.3
+ * @featureFlag translation
  *
  * @example
+ * To update translations by their ID:
+ * 
+ * ```ts
+ * const data = updateTranslationsStep({
+ *   translations: [
+ *     { id: "trans_123", translations: { title: "Nouveau titre" } }
+ *   ]
+ * })
+ * ```
+ * 
+ * To update translations matching filters:
+ * 
+ * ```ts
  * const data = updateTranslationsStep({
  *   selector: {
  *     reference_id: "prod_123",
@@ -43,6 +62,7 @@ export const updateTranslationsStepId = "update-translations"
  *     translations: { title: "Nouveau titre" }
  *   }
  * })
+ * ```
  */
 export const updateTranslationsStep = createStep(
   updateTranslationsStepId,

packages/core/core-flows/src/translation/steps/validate-translations.ts

@@ -15,7 +15,25 @@ export type ValidateTranslationsStepInput =
   | UpdateTranslationDTO
   | UpdateTranslationDataDTO
 
-// TODO: Do we want to validate anything else here?
+/**
+ * This step validates that the translations are supported by the store.
+ * 
+ * @since 2.12.3
+ * @featureFlag translation
+ * 
+ * @example
+ * const data = validateTranslationsStep([
+ *   {
+ *     reference_id: "prod_123",
+ *     reference: "product",
+ *     locale: "fr-FR",
+ *     translations: { title: "Produit", description: "Description du produit" }
+ *   }
+ * ])
+ * 
+ * @privateRemarks
+ * TODO: Do we want to validate anything else here?
+ */
 export const validateTranslationsStep = createStep(
   validateTranslationsStepId,
   async (data: ValidateTranslationsStepInput, { container }) => {

packages/core/core-flows/src/translation/workflows/batch-translations.ts

@@ -11,11 +11,65 @@ import { updateTranslationsWorkflow } from "./update-translations"
 
 export const batchTranslationsWorkflowId = "batch-translations"
 
+/**
+ * The translations to manage.
+ */
 export type BatchTranslationsWorkflowInput = {
+  /**
+   * The translations to create.
+   */
   create: CreateTranslationDTO[]
+  /**
+   * The translations to update.
+   */
   update: UpdateTranslationDTO[]
+  /**
+   * The IDs of the translations to delete.
+   */
   delete: string[]
 }
+/**
+ * This workflow creates, updates, and deletes translations. It's used by the
+ * [Manage Translations Admin API Route](https://docs.medusajs.com/api/admin#translations_posttranslationsbatch).
+ *
+ * You can use this workflow within your own customizations or custom workflows, allowing you
+ * to create, update, and delete translations in your custom flows.
+ * 
+ * @since 2.12.3
+ * @featureFlag translation
+ *
+ * @example
+ * const { result } = await batchTranslationsWorkflow(container)
+ * .run({
+ *   input: {
+ *     create: [
+ *       {
+ *         reference_id: "prod_123",
+ *         reference: "product",
+ *         locale_code: "en-US",
+ *         translations: {
+ *           title: "Product Title",
+ *           description: "Product Description",
+ *         },
+ *       }
+ *     ],
+ *     update: [
+ *       {
+ *         id: "trans_123",
+ *         translations: {
+ *           title: "Product Title",
+ *           description: "Product Description",
+ *         },
+ *       }
+ *     ],
+ *     delete: ["trans_321"]
+ *   }
+ * })
+ *
+ * @summary
+ *
+ * Create, update, and delete translations.
+ */
 export const batchTranslationsWorkflow = createWorkflow(
   batchTranslationsWorkflowId,
   (input: BatchTranslationsWorkflowInput) => {

packages/core/core-flows/src/translation/workflows/create-translations.ts

@@ -10,16 +10,26 @@ import { createTranslationsStep } from "../steps"
 import { validateTranslationsStep } from "../steps"
 import { TranslationWorkflowEvents } from "@medusajs/framework/utils"
 
+/**
+ * The translations to create.
+ */
 export type CreateTranslationsWorkflowInput = {
+  /**
+   * The translations to create.
+   */
   translations: CreateTranslationDTO[]
 }
 
 export const createTranslationsWorkflowId = "create-translations"
 /**
- * This workflow creates one or more translations.
+ * This workflow creates one or more translations. It's used by other workflows
+ * like the {@link batchTranslationsWorkflow} workflow.
  *
  * You can use this workflow within your own customizations or custom workflows, allowing you
  * to create translations in your custom flows.
+ * 
+ * @since 2.12.3
+ * @featureFlag translation
  *
  * @example
  * const { result } = await createTranslationsWorkflow(container)

packages/core/core-flows/src/translation/workflows/delete-translations.ts

@@ -7,14 +7,26 @@ import { emitEventStep } from "../../common/steps/emit-event"
 import { deleteTranslationsStep } from "../steps"
 import { TranslationWorkflowEvents } from "@medusajs/framework/utils"
 
-export type DeleteTranslationsWorkflowInput = { ids: string[] }
+/**
+ * The IDs of the translations to delete.
+ */
+export type DeleteTranslationsWorkflowInput = {
+  /**
+   * The IDs of the translations to delete.
+   */
+  ids: string[]
+}
 
 export const deleteTranslationsWorkflowId = "delete-translations"
 /**
- * This workflow deletes one or more translations.
+ * This workflow deletes one or more translations. It's used by other
+ * workflows like the {@link batchTranslationsWorkflow} workflow.
  *
  * You can use this workflow within your own customizations or custom workflows, allowing you
  * to delete translations in your custom flows.
+ * 
+ * @since 2.12.3
+ * @featureFlag translation
  *
  * @example
  * const { result } = await deleteTranslationsWorkflow(container)

packages/core/core-flows/src/translation/workflows/update-translations.ts

@@ -10,28 +10,47 @@ import { updateTranslationsStep, UpdateTranslationsStepInput } from "../steps"
 import { validateTranslationsStep } from "../steps"
 import { TranslationWorkflowEvents } from "@medusajs/framework/utils"
 
+/**
+ * The translations to update.
+ */
 export type UpdateTranslationsWorkflowInput = UpdateTranslationsStepInput
 
 export const updateTranslationsWorkflowId = "update-translations"
 /**
- * This workflow updates translations matching the specified filters.
+ * This workflow updates translations matching the specified filters or IDs. It's used by other
+ * workflows like the {@link batchTranslationsWorkflow} workflow.
  *
  * You can use this workflow within your own customizations or custom workflows, allowing you
  * to update translations in your custom flows.
+ * 
+ * @since 2.12.3
+ * @featureFlag translation
  *
  * @example
+ * To update translations by their IDs:
+ * 
+ * ```ts
  * const { result } = await updateTranslationsWorkflow(container)
  * .run({
  *   input: {
- *     selector: {
- *       reference_id: "prod_123",
- *       locale: "fr-FR"
- *     },
- *     update: {
- *       translations: { title: "Nouveau titre" }
- *     }
+ *     translations: [
+ *       { id: "trans_123", translations: { title: "Nouveau titre" } }
+ *     ]
  *   }
  * })
+ * ```
+ *
+ * To update translations matching filters:
+ *
+ * ```ts
+ * const { result } = await updateTranslationsWorkflow(container)
+ * .run({
+ *   input: {
+ *     selector: { reference_id: "prod_123", locale: "fr-FR" },
+ *     update: { translations: { title: "Nouveau titre" } }
+ *   }
+ * })
+ * ```
  *
  * @summary
  *