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: {
+ *     translations: [
- *       reference_id: "prod_123",
+ *       { id: "trans_123", translations: { title: "Nouveau titre" } }
- *       locale: "fr-FR"
+ *     ]
- *     },
- *     update: {
- *       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
  *

packages/core/js-sdk/src/admin/index.ts

@@ -182,6 +182,7 @@ export class Admin {
   public currency: Currency
   /**
    * @tags locale
+   * @since 2.12.3
    */
   public locale: Locale
   /**

packages/core/js-sdk/src/admin/locale.ts

@@ -27,7 +27,7 @@ export class Locale {
    * To retrieve the list of locales:
    *
    * ```ts
-   * sdk.admin.locales.list()
+   * sdk.admin.locale.list()
    * .then(({ locales, count, limit, offset }) => {
    *   console.log(locales)
    * })
@@ -38,7 +38,7 @@ export class Locale {
    * For example, to retrieve only 10 items and skip 10 items:
    *
    * ```ts
-   * sdk.admin.locales.list({
+   * sdk.admin.locale.list({
    *   limit: 10,
    *   offset: 10
    * })
@@ -51,7 +51,7 @@ export class Locale {
    * in each locale:
    *
    * ```ts
-   * sdk.admin.locales.list({
+   * sdk.admin.locale.list({
    *   fields: "code,name"
    * })
    * .then(({ locales, count, limit, offset }) => {
@@ -75,7 +75,7 @@ export class Locale {
    * This method retrieves a locale by its code. It sends a request to the
    * [Get Locale](https://docs.medusajs.com/api/admin#locales_getlocalescode) API route.
    *
-   * @param code - The locale's code.
+   * @param code - The locale's code in BCP 47 format.
    * @param query - Configure the fields to retrieve in the locale.
    * @param headers - Headers to pass in the request
    * @returns The locale's details.

packages/core/types/src/cart/workflows.ts

@@ -281,7 +281,12 @@ export interface CreateCartWorkflowInputDTO {
   promo_codes?: string[]
 
   /**
-   * The locale code of the cart.
+   * The locale code of the cart in BCP 47 format.
+   * 
+   * @since 2.12.3
+   * 
+   * @example
+   * "en-US"
    */
   locale?: string
 }
@@ -342,7 +347,12 @@ export interface UpdateCartWorkflowInputDTO {
   currency_code?: string
 
   /**
-   * The locale code for the cart.
+   * The locale code for the cart in BCP 47 format.
+   * 
+   * @since 2.12.3
+   * 
+   * @example
+   * "en-US"
    */
   locale?: string | null
 

packages/core/types/src/http/cart/store/payloads.ts

@@ -41,7 +41,12 @@ export interface StoreCreateCart {
   metadata?: Record<string, unknown>
 
   /**
-   * The locale code of the cart.
+   * The BCP 47 language tag code of the locale.
+   * 
+   * @since 2.12.3
+   * 
+   * @example
+   * "en-US"
    */
   locale?: string
 }
@@ -77,7 +82,12 @@ export interface StoreUpdateCart {
    */
   promo_codes?: string[]
   /**
-   * The locale code of the cart.
+   * The BCP 47 language tag code of the locale.
+   * 
+   * @since 2.12.3
+   * 
+   * @example
+   * "en-US"
    */
   locale?: string
 }

packages/core/types/src/http/locale/admin/queries.ts

@@ -11,7 +11,10 @@ export interface AdminLocaleListParams
    */
   q?: string
   /**
-   * Filter by locale code(s).
+   * Filter by locale code(s) in BCP 47 format.
+   * 
+   * @example
+   * "en-US"
    */
   code?: string | string[]
 }

packages/core/types/src/http/locale/common.ts

@@ -7,7 +7,7 @@ export interface BaseLocale {
    */
   code: string
   /**
-   * The locale's name.
+   * The locale's display name.
    *
    * @example
    * English (United States)

packages/core/types/src/http/locale/store/responses.ts

@@ -1,5 +1,8 @@
 import { StoreLocale } from "./entities";
 
 export interface StoreLocaleListResponse {
+  /**
+   * The list of locales.
+   */
   locales: StoreLocale[]
 }

packages/core/types/src/http/order/admin/payload.ts

@@ -15,6 +15,8 @@ export interface AdminUpdateOrder {
    * The order's locale code. Items in the 
    * order will be translated to the given locale,
    * if translations are available.
+   * 
+   * @since 2.12.3
    */
   locale?: string | null
   /**

packages/core/types/src/http/store/admin/payloads.ts

@@ -24,6 +24,9 @@ export interface AdminUpdateStoreSupportedCurrency {
 export interface AdminUpdateStoreSupportedLocale {
   /**
    * The locale's BCP 47 language tag.
+   * 
+   * @example
+   * "en-US"
    */
   locale_code: string
 }
@@ -42,6 +45,8 @@ export interface AdminUpdateStore {
   supported_currencies?: AdminUpdateStoreSupportedCurrency[]
   /**
    * The supported locales of the store.
+   * 
+   * @since 2.12.3
    */
   supported_locales?: AdminUpdateStoreSupportedLocale[]
   /**

packages/core/types/src/http/translations/admin/entities.ts

@@ -6,21 +6,37 @@ export interface AdminTranslation {
 
   /**
    * The ID of the entity being translated.
+   * 
+   * @example
+   * "prod_123"
    */
   reference_id: string
 
   /**
-   * The type of entity being translated (e.g., "product", "product_variant").
+   * The name of the table that the translation belongs to.
+   * 
+   * @example
+   * "product"
    */
   reference: string
 
   /**
-   * The BCP 47 language tag code for this translation (e.g., "en-US", "fr-FR").
+   * The BCP 47 language tag code for this translation.
+   * 
+   * @example
+   * "en-US"
    */
   locale_code: string
 
   /**
-   * The translated fields as key-value pairs.
+   * The translations of the resource.
+   * The object's keys are the field names of the data model, and its value is the translated value.
+   * 
+   * @example
+   * {
+   *   "title": "Product Title",
+   *   "description": "Product Description",
+   * }
    */
   translations: Record<string, unknown>
 

packages/core/types/src/http/translations/admin/queries.ts

@@ -10,14 +10,23 @@ export interface AdminTranslationsListParams
   q?: string
   /**
    * Filter by entity ID.
+   * 
+   * @example
+   * "prod_123"
    */
   reference_id?: string | string[]
   /**
-   * Filter by entity type.
+   * Filter by the table of the resource being translated.
+   * 
+   * @example
+   * "product"
    */
   reference?: string
   /**
-   * Filter by locale code.
+   * Filter by locale code in BCP 47 format.
+   * 
+   * @example
+   * "en-US"
    */
   locale_code?: string | string[]
 }
@@ -27,12 +36,18 @@ export interface AdminTranslationsListParams
  */
 export interface AdminTranslationStatisticsParams {
   /**
-   * The locales to check translations for (e.g., ["en-US", "fr-FR"]).
+   * The locales to check translations for.
+   * 
+   * @example
+   * ["en-US", "fr-FR"]
    */
   locales: string[]
 
   /**
-   * The entity types to get statistics for (e.g., ["product", "product_variant"]).
+   * The entity types to get statistics for.
+   * 
+   * @example
+   * ["product", "product_variant"]
    */
   entity_types: string[]
 }

packages/core/types/src/http/translations/admin/responses.ts

@@ -28,8 +28,17 @@ export interface AdminTranslationsBatchResponse {
    * The deleted translations.
    */
   deleted: {
+    /**
+     * The IDs of the deleted translations.
+     */
     ids: string[]
+    /**
+     * The name of the deleted object.
+     */
     object: "translation"
+    /**
+     * Whether the translations were deleted successfully.
+     */
     deleted: boolean
   }
 }
@@ -43,11 +52,13 @@ export interface AdminTranslationLocaleStatistics {
    */
   expected: number
   /**
-   * Actual number of translated fields.
+   * Actual number of translated fields. This doesn't count
+   * translations that are null or empty.
    */
   translated: number
   /**
-   * Number of missing translations.
+   * Number of missing translations for expected translatable
+   * fields.
    */
   missing: number
 }

packages/core/types/src/translation/common.ts

@@ -138,15 +138,25 @@ export interface FilterableTranslationProps
  */
 export interface TranslationStatisticsInput {
   /**
-   * Locales to check translations for (e.g., ["en-US", "fr-FR"]).
+   * Locales to check translations for.
+   * 
+   * @example
+   * ["en-US", "fr-FR"]
    */
   locales: string[]
 
   /**
-   * Entity types with their total counts.
+   * Key-value pairs of entity types and their configurations.
-   * Key is the entity type (e.g., "product"), value contains the count of entities.
    */
-  entities: Record<string, { count: number }>
+  entities: Record<string, {
+    /**
+     * Total number of records for the entity type.
+     * For example, total number of products.
+     * 
+     * This is necessary to compute expected translation counts.
+     */ 
+    count: number
+  }>
 }
 
 /**
@@ -154,17 +164,19 @@ export interface TranslationStatisticsInput {
  */
 export interface LocaleStatistics {
   /**
-   * Expected number of translated fields.
+   * Expected total number of translated fields.
    */
   expected: number
 
   /**
-   * Actual number of translated fields (non-null, non-empty).
+   * Actual number of translated fields. This doesn't count
+   * translations that are null or empty.
    */
   translated: number
 
   /**
-   * Number of missing translations (expected - translated).
+   * Number of missing translations for expected translatable
+   * fields.
    */
   missing: number
 }

packages/core/types/src/translation/mutations.ts

@@ -8,12 +8,18 @@ export interface CreateLocaleDTO {
   id?: string
 
   /**
-   * The BCP 47 language tag code of the locale (e.g., "en-US", "fr-FR").
+   * The BCP 47 language tag code of the locale.
+   * 
+   * @example
+   * "en-US"
    */
   code: string
 
   /**
-   * The human-readable name of the locale (e.g., "English (United States)").
+   * The human-readable name of the locale.
+   * 
+   * @example
+   * "English (United States)"
    */
   name: string
 }
@@ -24,11 +30,17 @@ export interface CreateLocaleDTO {
 export interface UpdateLocaleDataDTO {
   /**
    * The BCP 47 language tag code of the locale.
+   * 
+   * @example
+   * "en-US"
    */
   code?: string
 
   /**
    * The human-readable name of the locale.
+   * 
+   * @example
+   * "English (United States)"
    */
   name?: string
 }
@@ -54,11 +66,17 @@ export interface UpsertLocaleDTO {
 
   /**
    * The BCP 47 language tag code of the locale.
+   * 
+   * @example
+   * "en-US"
    */
   code?: string
 
   /**
    * The human-readable name of the locale.
+   * 
+   * @example
+   * "English (United States)"
    */
   name?: string
 }
@@ -68,22 +86,37 @@ export interface UpsertLocaleDTO {
  */
 export interface CreateTranslationDTO {
   /**
-   * The ID of the entity being translated.
+   * The ID of the data model being translated.
+   * 
+   * @example
+   * "prod_123"
    */
   reference_id: string
 
   /**
-   * The type of entity being translated (e.g., "product", "product_variant").
+   * The name of the table that the translation belongs to.
+   * 
+   * @example
+   * "product"
    */
   reference: string
 
   /**
-   * The BCP 47 language tag code for this translation (e.g., "en-US", "fr-FR").
+   * The BCP 47 language tag code for this translation.
+   * 
+   * @example
+   * "en-US"
    */
   locale_code: string
 
   /**
    * The translated fields as key-value pairs.
+   * 
+   * @example
+   * {
+   *   "title": "Product Title",
+   *   "description": "Product Description",
+   * }
    */
   translations: Record<string, unknown>
 }
@@ -93,22 +126,37 @@ export interface CreateTranslationDTO {
  */
 export interface UpdateTranslationDataDTO {
   /**
-   * The ID of the entity being translated.
+   * The ID of the data model being translated.
+   * 
+   * @example
+   * "prod_123"
    */
   reference_id?: string
 
   /**
-   * The type of entity being translated.
+   * The name of the table that the translation belongs to.
+   * 
+   * @example
+   * "product"
    */
   reference?: string
 
   /**
    * The BCP 47 language tag code for this translation.
+   * 
+   * @example
+   * "en-US"
    */
   locale_code?: string
 
   /**
    * The translated fields as key-value pairs.
+   * 
+   * @example
+   * {
+   *   "title": "Product Title",
+   *   "description": "Product Description",
+   * }
    */
   translations?: Record<string, unknown>
 }
@@ -133,22 +181,37 @@ export interface UpsertTranslationDTO {
   id?: string
 
   /**
-   * The ID of the entity being translated.
+   * The ID of the data model being translated.
+   * 
+   * @example
+   * "prod_123"
    */
   reference_id?: string
 
   /**
-   * The type of entity being translated.
+   * The name of the table that the translation belongs to.
+   * 
+   * @example
+   * "product"
    */
   reference?: string
 
   /**
    * The BCP 47 language tag code for this translation.
+   * 
+   * @example
+   * "en-US"
    */
   locale_code?: string
 
   /**
    * The translated fields as key-value pairs.
+   * 
+   * @example
+   * {
+   *   "title": "Product Title",
+   *   "description": "Product Description",
+   * }
    */
   translations?: Record<string, unknown>
 }

packages/core/types/src/translation/service.ts

@@ -21,6 +21,8 @@ import {
 
 /**
  * The main service interface for the Translation Module.
+ * 
+ * @privateRemarks
  * Method signatures match what MedusaService generates.
  */
 export interface ITranslationModuleService extends IModuleService {
@@ -28,9 +30,32 @@ export interface ITranslationModuleService extends IModuleService {
    * This method retrieves a locale by its ID.
    *
    * @param {string} id - The ID of the locale.
-   * @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved.
+   * @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
-   * @param {Context} sharedContext
+   * attributes or relations associated with a locale.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<LocaleDTO>} The retrieved locale.
+   *
+   * @example
+   * A simple example that retrieves a locale by its ID:
+   *
+   * ```ts
+   * const locale = await translationModuleService.retrieveLocale("loc_123")
+   * ```
+   *
+   * To specify relations that should be retrieved:
+   * 
+   * :::note
+   * 
+   * You can only retrieve data models defined in the same module. To retrieve linked data models
+   * from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.
+   * 
+   * :::
+   *
+   * ```ts
+   * const locale = await translationModuleService.retrieveLocale("loc_123", {
+   *   relations: ["translations"],
+   * })
+   * ```
    */
   retrieveLocale(
     id: string,
@@ -42,9 +67,54 @@ export interface ITranslationModuleService extends IModuleService {
    * This method retrieves a paginated list of locales based on optional filters and configuration.
    *
    * @param {FilterableLocaleProps} filters - The filters to apply on the retrieved locales.
-   * @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved.
+   * @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
-   * @param {Context} sharedContext
+   * attributes or relations associated with a locale.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<LocaleDTO[]>} The list of locales.
+   *
+   * @example
+   * To retrieve a list of locales using their IDs:
+   *
+   * ```ts
+   * const locales = await translationModuleService.listLocales({
+   *   id: ["loc_123", "loc_321"],
+   * })
+   * ```
+   *
+   * To specify relations that should be retrieved within the locales:
+   * 
+   * :::note
+   * 
+   * You can only retrieve data models defined in the same module. To retrieve linked data models
+   * from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.
+   * 
+   * :::
+   *
+   * ```ts
+   * const locales = await translationModuleService.listLocales(
+   *   {
+   *     id: ["loc_123", "loc_321"],
+   *   },
+   *   {
+   *     relations: ["translations"],
+   *   }
+   * )
+   * ```
+   *
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const locales = await translationModuleService.listLocales(
+   *   {
+   *     id: ["loc_123", "loc_321"],
+   *   },
+   *   {
+   *     relations: ["translations"],
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
+   * ```
    */
   listLocales(
     filters?: FilterableLocaleProps,
@@ -56,9 +126,54 @@ export interface ITranslationModuleService extends IModuleService {
    * This method retrieves a paginated list of locales along with the total count.
    *
    * @param {FilterableLocaleProps} filters - The filters to apply on the retrieved locales.
-   * @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved.
+   * @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
-   * @param {Context} sharedContext
+   * attributes or relations associated with a locale.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<[LocaleDTO[], number]>} The list of locales along with their total count.
+   *
+   * @example
+   * To retrieve a list of locales using their IDs:
+   *
+   * ```ts
+   * const [locales, count] = await translationModuleService.listAndCountLocales({
+   *   id: ["loc_123", "loc_321"],
+   * })
+   * ```
+   *
+   * To specify relations that should be retrieved within the locales:
+   * 
+   * :::note
+   * 
+   * You can only retrieve data models defined in the same module. To retrieve linked data models
+   * from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.
+   * 
+   * :::
+   *
+   * ```ts
+   * const [locales, count] = await translationModuleService.listAndCountLocales(
+   *   {
+   *     id: ["loc_123", "loc_321"],
+   *   },
+   *   {
+   *     relations: ["translations"],
+   *   }
+   * )
+   * ```
+   *
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const [locales, count] = await translationModuleService.listAndCountLocales(
+   *   {
+   *     id: ["loc_123", "loc_321"],
+   *   },
+   *   {
+   *     relations: ["translations"],
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
+   * ```
    */
   listAndCountLocales(
     filters?: FilterableLocaleProps,
@@ -70,8 +185,14 @@ export interface ITranslationModuleService extends IModuleService {
    * This method creates a locale.
    *
    * @param {CreateLocaleDTO} data - The locale to be created.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<LocaleDTO>} The created locale.
+   *
+   * @example
+   * const locale = await translationModuleService.createLocales({
+   *   code: "en-US",
+   *   name: "English (United States)",
+   * })
    */
   createLocales(
     data: CreateLocaleDTO,
@@ -82,8 +203,20 @@ export interface ITranslationModuleService extends IModuleService {
    * This method creates locales.
    *
    * @param {CreateLocaleDTO[]} data - The locales to be created.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<LocaleDTO[]>} The created locales.
+   *
+   * @example
+   * const locales = await translationModuleService.createLocales([
+   *   {
+   *     code: "en-US",
+   *     name: "English (United States)",
+   *   },
+   *   {
+   *     code: "fr-FR",
+   *     name: "French (France)",
+   *   },
+   * ])
    */
   createLocales(
     data: CreateLocaleDTO[],
@@ -94,8 +227,14 @@ export interface ITranslationModuleService extends IModuleService {
    * This method updates an existing locale. The ID should be included in the data object.
    *
    * @param {UpdateLocaleDTO} data - The attributes to update in the locale (including id).
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<LocaleDTO>} The updated locale.
+   *
+   * @example
+   * const locale = await translationModuleService.updateLocales({
+   *   id: "loc_123",
+   *   name: "English (United States)",
+   * })
    */
   updateLocales(
     data: UpdateLocaleDTO,
@@ -103,17 +242,52 @@ export interface ITranslationModuleService extends IModuleService {
   ): Promise<LocaleDTO>
 
   /**
-   * This method updates existing locales using an array or selector-based approach.
+   * This method updates existing locales either by ID or by a selector.
    *
    * @param {UpdateLocaleDTO[] | { selector: Record<string, any>; data: UpdateLocaleDTO | UpdateLocaleDTO[] }} dataOrOptions - The data or options for bulk update.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<LocaleDTO[]>} The updated locales.
+   *
+   * @example
+   * To update locales by their IDs:
+   * 
+   * ```ts
+   * const locales = await translationModuleService.updateLocales([
+   *   {
+   *     id: "loc_123",
+   *     name: "English (United States)",
+   *   },
+   *  {
+   *     id: "loc_321",
+   *     name: "French (France)",
+   *   },
+   * ])
+   * ```
+   *
+   * To update locales by a selector:
+   * 
+   * ```ts
+   * const locales = await translationModuleService.updateLocales({
+   *   selector: {
+   *     code: "en-US",
+   *   },
+   *   data: {
+   *     name: "English (United States)",
+   *   },
+   * })
+   * ```
    */
   updateLocales(
     dataOrOptions:
       | UpdateLocaleDTO[]
       | {
+          /**
+           * The selector to update the locales by.
+           */
           selector: Record<string, any>
+          /**
+           * The data to update the locales with.
+           */
           data: UpdateLocaleDataDTO | UpdateLocaleDataDTO[]
         },
     sharedContext?: Context
@@ -122,9 +296,12 @@ export interface ITranslationModuleService extends IModuleService {
   /**
    * This method deletes locales by their IDs or objects.
    *
-   * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects identifying the locales to delete.
+   * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects with IDs identifying the locales to delete.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<void>} Resolves when the locales are deleted.
+   * 
+   * @example
+   * await translationModuleService.deleteLocales(["loc_123", "loc_321"])
    */
   deleteLocales(
     primaryKeyValues: string | object | string[] | object[],
@@ -135,9 +312,13 @@ export interface ITranslationModuleService extends IModuleService {
    * This method soft deletes locales by their IDs or objects.
    *
    * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects identifying the locales to soft delete.
-   * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object for related entities that should be soft-deleted.
+   * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<Record<string, string[]> | void>} An object with IDs of related records that were also soft deleted.
+   * @returns {Promise<Record<string, string[]> | void>} An object that includes the IDs of related records that were also soft deleted.
+   * If there are no related records, the promise resolves to `void`.
+   *
+   * @example
+   * await translationModuleService.softDeleteLocales(["loc_123", "loc_321"])
    */
   softDeleteLocales<TReturnableLinkableKeys extends string = string>(
     primaryKeyValues: string | object | string[] | object[],
@@ -149,9 +330,15 @@ export interface ITranslationModuleService extends IModuleService {
    * This method restores soft deleted locales by their IDs or objects.
    *
    * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects identifying the locales to restore.
-   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the locale. You can pass to its `returnLinkableKeys`
-   * @param {Context} sharedContext
+   * property any of the locale's relation attribute names.
-   * @returns {Promise<Record<string, string[]> | void>} An object with IDs of related records that were restored.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<Record<string, string[]> | void>} An object that includes the IDs of related records that were restored.
+   *
+   * If there are no related records restored, the promise resolves to `void`.
+   * 
+   * @example
+   * await translationModuleService.restoreLocales(["loc_123", "loc_321"])
    */
   restoreLocales<TReturnableLinkableKeys extends string = string>(
     primaryKeyValues: string | object | string[] | object[],
@@ -164,8 +351,30 @@ export interface ITranslationModuleService extends IModuleService {
    *
    * @param {string} id - The ID of the translation.
    * @param {FindConfig<TranslationDTO>} config - The configurations determining how the translation is retrieved.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<TranslationDTO>} The retrieved translation.
+   *
+   * @example
+   * A simple example that retrieves a translation by its ID:
+   *
+   * ```ts
+   * const translation = await translationModuleService.retrieveTranslation("tra_123")
+   * ```
+   *
+   * To specify relations that should be retrieved:
+   * 
+   * :::note
+   * 
+   * You can only retrieve data models defined in the same module. To retrieve linked data models
+   * from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.
+   * 
+   * :::
+   *
+   * ```ts
+   * const translation = await translationModuleService.retrieveTranslation("tra_123", {
+   *   relations: ["locale"],
+   * })
+   * ```
    */
   retrieveTranslation(
     id: string,
@@ -177,9 +386,54 @@ export interface ITranslationModuleService extends IModuleService {
    * This method retrieves a paginated list of translations based on optional filters and configuration.
    *
    * @param {FilterableTranslationProps} filters - The filters to apply on the retrieved translations.
-   * @param {FindConfig<TranslationDTO>} config - The configurations determining how the translation is retrieved.
+   * @param {FindConfig<TranslationDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
-   * @param {Context} sharedContext
+   * attributes or relations associated with a locale.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<TranslationDTO[]>} The list of translations.
+   *
+   * @example
+   * To retrieve a list of translations using their IDs:
+   *
+   * ```ts
+   * const translations = await translationModuleService.listTranslations({
+   *   id: ["tra_123", "tra_321"],
+   * })
+   * ```
+   *
+   * To specify relations that should be retrieved within the translations:
+   * 
+   * :::note
+   * 
+   * You can only retrieve data models defined in the same module. To retrieve linked data models
+   * from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.
+   * 
+   * :::
+   *
+   * ```ts
+   * const translations = await translationModuleService.listTranslations(
+   *   {
+   *     id: ["tra_123", "tra_321"],
+   *   },
+   *   {
+   *     relations: ["locale"],
+   *   }
+   * )
+   * ```
+   * 
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const translations = await translationModuleService.listTranslations(
+   *   {
+   *     id: ["tra_123", "tra_321"],
+   *   },
+   *   {
+   *     relations: ["locale"],
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
+   * ```
    */
   listTranslations(
     filters?: FilterableTranslationProps,
@@ -191,9 +445,54 @@ export interface ITranslationModuleService extends IModuleService {
    * This method retrieves a paginated list of translations along with the total count.
    *
    * @param {FilterableTranslationProps} filters - The filters to apply on the retrieved translations.
-   * @param {FindConfig<TranslationDTO>} config - The configurations determining how the translation is retrieved.
+   * @param {FindConfig<TranslationDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
-   * @param {Context} sharedContext
+   * attributes or relations associated with a locale.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<[TranslationDTO[], number]>} The list of translations along with their total count.
+   *
+   * @example
+   * To retrieve a list of translations using their IDs:
+   *
+   * ```ts
+   * const [translations, count] = await translationModuleService.listAndCountTranslations({
+   *   id: ["tra_123", "tra_321"],
+   * })
+   * ```
+   *
+   * To specify relations that should be retrieved within the translations:
+   * 
+   * :::note
+   * 
+   * You can only retrieve data models defined in the same module. To retrieve linked data models
+   * from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.
+   * 
+   * :::
+   *
+   * ```ts
+   * const [translations, count] = await translationModuleService.listAndCountTranslations(
+   *   {
+   *     id: ["tra_123", "tra_321"],
+   *   },
+   *   {
+   *     relations: ["locale"],
+   *   }
+   * )
+   * ```
+   * 
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const [translations, count] = await translationModuleService.listAndCountTranslations(
+   *   {
+   *     id: ["tra_123", "tra_321"],
+   *   },
+   *   {
+   *     relations: ["locale"],
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
+   * ```
    */
   listAndCountTranslations(
     filters?: FilterableTranslationProps,
@@ -205,8 +504,19 @@ export interface ITranslationModuleService extends IModuleService {
    * This method creates a translation.
    *
    * @param {CreateTranslationDTO} data - The translation to be created.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<TranslationDTO>} The created translation.
+   *
+   * @example
+   * const translation = await translationModuleService.createTranslations({
+   *   reference_id: "prod_123",
+   *   reference: "product",
+   *   locale_code: "fr-FR",
+   *   translations: {
+   *     title: "Titre du produit",
+   *     description: "Description du produit en français",
+   *   },
+   * })
    */
   createTranslations(
     data: CreateTranslationDTO,
@@ -217,8 +527,30 @@ export interface ITranslationModuleService extends IModuleService {
    * This method creates translations.
    *
    * @param {CreateTranslationDTO[]} data - The translations to be created.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<TranslationDTO[]>} The created translations.
+   *
+   * @example
+   * const translations = await translationModuleService.createTranslations([
+   *   {
+   *     reference_id: "prod_123",
+   *     reference: "product",
+   *     locale_code: "fr-FR",
+   *     translations: {
+   *       title: "Titre du produit",
+   *       description: "Description du produit en français",
+   *     },
+   *   },
+   *   {
+   *     reference_id: "prod_123",
+   *     reference: "product",
+   *     locale_code: "de-DE",
+   *     translations: {
+   *       title: "Produkt Titel",
+   *       description: "Produktbeschreibung auf Deutsch",
+   *     },
+   *   }
+   * ])
    */
   createTranslations(
     data: CreateTranslationDTO[],
@@ -229,8 +561,17 @@ export interface ITranslationModuleService extends IModuleService {
    * This method updates an existing translation. The ID should be included in the data object.
    *
    * @param {UpdateTranslationDTO} data - The attributes to update in the translation (including id).
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<TranslationDTO>} The updated translation.
+   *
+   * @example
+   * const translation = await translationModuleService.updateTranslations({
+   *   id: "tra_123",
+   *   translations: {
+   *     title: "Titre du produit",
+   *     description: "Description du produit en français",
+   *   },
+   * })
    */
   updateTranslations(
     data: UpdateTranslationDTO,
@@ -241,14 +582,31 @@ export interface ITranslationModuleService extends IModuleService {
    * This method updates existing translations using an array or selector-based approach.
    *
    * @param {UpdateTranslationDTO[] | { selector: Record<string, any>; data: UpdateTranslationDTO | UpdateTranslationDTO[] }} dataOrOptions - The data or options for bulk update.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<TranslationDTO[]>} The updated translations.
+   *
+   * @example
+   * const translations = await translationModuleService.updateTranslations([
+   *   {
+   *     id: "tra_123",
+   *     translations: {
+   *       title: "Titre du produit",
+   *       description: "Description du produit en français",
+   *     },
+   *   },
+   * ])
    */
   updateTranslations(
     dataOrOptions:
       | UpdateTranslationDTO[]
       | {
+          /**
+           * The selector to update the translations by.
+           */
           selector: Record<string, any>
+          /**
+           * The data to update the translations with.
+           */
           data: UpdateTranslationDataDTO | UpdateTranslationDataDTO[]
         },
     sharedContext?: Context
@@ -257,9 +615,12 @@ export interface ITranslationModuleService extends IModuleService {
   /**
    * This method deletes translations by their IDs or objects.
    *
-   * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects identifying the translations to delete.
+   * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects with IDs identifying the translations to delete.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<void>} Resolves when the translations are deleted.
+   * 
+   * @example
+   * await translationModuleService.deleteTranslations("tra_123")
    */
   deleteTranslations(
     primaryKeyValues: string | object | string[] | object[],
@@ -269,10 +630,14 @@ export interface ITranslationModuleService extends IModuleService {
   /**
    * This method soft deletes translations by their IDs or objects.
    *
-   * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects identifying the translations to soft delete.
+   * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects with IDs identifying the translations to soft delete.
-   * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object for related entities that should be soft-deleted.
+   * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
-   * @param {Context} sharedContext
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<Record<string, string[]> | void>} An object with IDs of related records that were also soft deleted.
+   * @returns {Promise<Record<string, string[]> | void>} An object that includes the IDs of related records that were also soft deleted.
+   * If there are no related records, the promise resolves to `void`.
+   * 
+   * @example
+   * await translationModuleService.softDeleteTranslations(["tra_123", "tra_321"])
    */
   softDeleteTranslations<TReturnableLinkableKeys extends string = string>(
     primaryKeyValues: string | object | string[] | object[],
@@ -283,10 +648,15 @@ export interface ITranslationModuleService extends IModuleService {
   /**
    * This method restores soft deleted translations by their IDs or objects.
    *
-   * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects identifying the translations to restore.
+   * @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects with IDs identifying the translations to restore.
-   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore.
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the translation. You can pass to its `returnLinkableKeys`
-   * @param {Context} sharedContext
+   * property any of the translation's relation attribute names.
-   * @returns {Promise<Record<string, string[]> | void>} An object with IDs of related records that were restored.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<Record<string, string[]> | void>} An object that includes the IDs of related records that were restored.
+   * If there are no related records restored, the promise resolves to `void`.
+   *
+   * @example
+   * await translationModuleService.restoreTranslations(["tra_123", "tra_321"])
    */
   restoreTranslations<TReturnableLinkableKeys extends string = string>(
     primaryKeyValues: string | object | string[] | object[],
@@ -295,20 +665,24 @@ export interface ITranslationModuleService extends IModuleService {
   ): Promise<Record<string, string[]> | void>
 
   /**
-   * This method retrieves translation statistics for the given entities and locales.
+   * This method retrieves translation statistics for the specified entities and locales.
-   * It counts translated fields at a granular level, providing both aggregated
+   * It's useful to understand the translation coverage of different entities across various locales.
-   * and per-locale breakdowns.
+   * 
+   * You can use this method to get insights into how many fields are translated, missing translations,
+   * and the expected number of translations based on the entities and locales provided.
    *
    * @param {TranslationStatisticsInput} input - The entities and locales to check.
    * @param {Context} sharedContext
-   * @returns {Promise<TranslationStatisticsOutput>} Statistics by entity type.
+   * @returns {Promise<TranslationStatisticsOutput>} Statistics by entity.
    *
    * @example
-   * const stats = await translationService.getStatistics({
+   * const [,count] = await productModuleService.listAndCountProducts()
+   * const [,variantCount] = await productVariantModuleService.listAndCountProductVariants()
+   * const stats = await translationModuleService.getStatistics({
    *   locales: ["en-US", "fr-FR"],
    *   entities: {
-   *     product: { count: 2 },
+   *     product: { count }, // for example, 2 products
-   *     product_variant: { count: 5 }
+   *     product_variant: { count: variantCount },
    *   }
    * })
    * // Returns:
@@ -330,20 +704,27 @@ export interface ITranslationModuleService extends IModuleService {
   ): Promise<TranslationStatisticsOutput>
 
   /**
-   * This method retrieves the translatable fields configuration.
+   * This method retrieves the translatable fields of a resource. For example,
-   * Returns a mapping of entity types to their translatable field names.
+   * product entities have translatable fields such as `title` and `description`.
    *
-   * @param {string} entityType - Optional entity type to filter by. If not provided, returns all.
+   * @param {string} entityType - Name of the resource's table to get translatable fields for.
-   * @returns {Record<string, string[]>} A mapping of entity types to their translatable fields.
+   * If not provided, returns all translatable fields for all entity types. For example, `product` or `product_variant`.
+   * @returns {Record<string, string[]>} A mapping of resource names to their translatable fields.
    *
    * @example
-   * // Get all translatable fields
+   * To get translatable fields for all resources:
-   * const allFields = translationService.getTranslatableFields()
+   * 
+   * ```ts
+   * const allFields = translationModuleService.getTranslatableFields()
    * // Returns: { product: ["title", "description", ...], product_variant: ["title", ...] }
+   * ```
+   * 
+   * To get translatable fields for a specific resource:
    *
-   * // Get fields for a specific entity type
+   * ```ts
-   * const productFields = translationService.getTranslatableFields("product")
+   * const productFields = translationModuleService.getTranslatableFields("product")
    * // Returns: { product: ["title", "description", "subtitle", "status"] }
+   * ```
    */
   getTranslatableFields(entityType?: string): Record<string, string[]>
 }

packages/core/utils/src/core-flows/events.ts

@@ -898,7 +898,7 @@ export const TranslationWorkflowEvents = {
   /**
    * Emitted when translations are created.
    * 
-   * @since 2.13.0
+   * @since 2.12.3
    * @featureFlag translation
    * @eventPayload
    * ```ts
@@ -911,7 +911,7 @@ export const TranslationWorkflowEvents = {
   /**
    * Emitted when translations are updated.
    *
-   * @since 2.13.0
+   * @since 2.12.3
    * @featureFlag translation
    * @eventPayload
    * ```ts
@@ -924,7 +924,7 @@ export const TranslationWorkflowEvents = {
   /**
    * Emitted when translations are deleted.
    *
-   * @since 2.13.0
+   * @since 2.12.3
    * @featureFlag translation
    * @eventPayload
    * ```ts

packages/medusa/src/api/admin/locales/[code]/route.ts

@@ -5,6 +5,10 @@ import {
 import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
 import { HttpTypes } from "@medusajs/framework/types"
 
+/**
+ * @since 2.12.3
+ * @featureFlag translation
+ */
 export const GET = async (
   req: MedusaRequest<HttpTypes.AdminLocaleParams>,
   res: MedusaResponse<HttpTypes.AdminLocaleResponse>

packages/medusa/src/api/admin/locales/route.ts

@@ -2,6 +2,10 @@ import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
 import { HttpTypes } from "@medusajs/framework/types"
 
+/**
+ * @since 2.12.3
+ * @featureFlag translation
+ */
 export const GET = async (
   req: MedusaRequest<HttpTypes.AdminLocaleListParams>,
   res: MedusaResponse<HttpTypes.AdminLocaleListResponse>

packages/medusa/src/api/admin/translations/batch/route.ts

@@ -13,6 +13,10 @@ import {
   AdminUpdateTranslationType,
 } from "../validators"
 
+/**
+ * @since 2.12.3
+ * @featureFlag translation
+ */
 export const POST = async (
   req: AuthenticatedMedusaRequest<
     BatchMethodRequest<AdminCreateTranslationType, AdminUpdateTranslationType>

packages/medusa/src/api/admin/translations/route.ts

@@ -7,6 +7,10 @@ import {
 } from "@medusajs/framework/utils"
 import TranslationFeatureFlag from "../../../feature-flags/translation"
 
+/**
+ * @since 2.12.3
+ * @featureFlag translation
+ */
 export const GET = async (
   req: MedusaRequest<HttpTypes.AdminTranslationsListParams>,
   res: MedusaResponse<HttpTypes.AdminTranslationsListResponse>

packages/medusa/src/api/admin/translations/settings/route.ts

@@ -10,6 +10,10 @@ import {
 } from "@medusajs/framework/utils"
 import TranslationFeatureFlag from "../../../../feature-flags/translation"
 
+/**
+ * @since 2.12.3
+ * @featureFlag translation
+ */
 export const GET = async (
   req: AuthenticatedMedusaRequest,
   res: MedusaResponse<HttpTypes.AdminTranslationSettingsResponse>

packages/medusa/src/api/admin/translations/statistics/route.ts

@@ -12,9 +12,13 @@ import {
 } from "@medusajs/framework/utils"
 import TranslationFeatureFlag from "../../../../feature-flags/translation"
 
+/**
+ * @since 2.12.3
+ * @featureFlag translation
+ */
 export const GET = async (
   req: AuthenticatedMedusaRequest<
-    unknown,
+    {},
     HttpTypes.AdminTranslationStatisticsParams
   >,
   res: MedusaResponse<HttpTypes.AdminTranslationStatisticsResponse>

packages/medusa/src/api/store/locales/route.ts

@@ -2,6 +2,10 @@ import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
 import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 import { HttpTypes } from "@medusajs/framework/types"
 
+/**
+ * @since 2.12.3
+ * @featureFlag translation
+ */
 export const GET = async (
   req: MedusaRequest, 
   res: MedusaResponse<HttpTypes.StoreLocaleListResponse>

packages/modules/cart/src/models/cart.ts

@@ -12,6 +12,14 @@ const Cart = model
     sales_channel_id: model.text().nullable(),
     email: model.text().nullable(),
     currency_code: model.text(),
+    /**
+     * The BCP 47 language tag code of the locale
+     * 
+     * @since 2.12.3
+     * 
+     * @example
+     * "en-US"
+     */
     locale: model.text().nullable(),
     metadata: model.json().nullable(),
     completed_at: model.dateTime().nullable(),

packages/modules/store/src/models/locale.ts

@@ -1,8 +1,17 @@
 import { model } from "@medusajs/framework/utils"
 import Store from "./store"
 
+/**
+ * @since 2.12.3
+ */
 const StoreLocale = model.define("StoreLocale", {
   id: model.id({ prefix: "stloc" }).primaryKey(),
+  /**
+   * The BCP 47 language tag code of the locale.
+   * 
+   * @example
+   * "en-US"
+   */
   locale_code: model.text().searchable(),
   store: model
     .belongsTo(() => Store, {

packages/modules/store/src/models/store.ts

@@ -13,6 +13,11 @@ const Store = model
     supported_currencies: model.hasMany(() => StoreCurrency, {
       mappedBy: "store",
     }),
+    /**
+     * The supported locales of the store.
+     * 
+     * @since 2.12.3
+     */
     supported_locales: model.hasMany(() => StoreLocale, {
       mappedBy: "store",
     }),

packages/modules/translation/src/models/locale.ts

@@ -3,8 +3,14 @@ import { model } from "@medusajs/framework/utils"
 const Locale = model
   .define("locale", {
     id: model.id({ prefix: "loc" }).primaryKey(),
-    code: model.text().searchable(), // BCP 47 language tag, e.g., "en-US", "da-DK"
+    /**
-    name: model.text().searchable(), // Human-readable name, e.g., "English (US)", "Danish"
+     * The BCP 47 language tag code of the locale (e.g., "en-US", "da-DK").
+     */
+    code: model.text().searchable(),
+    /**
+     * The human-readable name of the locale (e.g., "English (US)", "Danish").
+     */
+    name: model.text().searchable(),
   })
   .indexes([
     {

packages/modules/translation/src/models/translation.ts

@@ -3,11 +3,37 @@ import { model } from "@medusajs/framework/utils"
 const Translation = model
   .define("translation", {
     id: model.id({ prefix: "trans" }).primaryKey(),
+    /**
+     * The ID of the entity that the translation belongs to. For example, the ID of a product or a product variant.
+     */
     reference_id: model.text().searchable(),
-    reference: model.text().searchable(), // e.g., "product", "product_variant", "product_category"
+    /**
-    locale_code: model.text().searchable(), // BCP 47 language tag, e.g., "en-US", "da-DK"
+     * The name of the table that the translation belongs to. For example, "product" or "product_variant".
+     */
+    reference: model.text().searchable(),
+    /**
+     * The BCP 47 language tag code of the locale
+     * 
+     * @example
+     * "en-US"
+     */
+    locale_code: model.text().searchable(),
+    /**
+     * The translations of the entity.
+     * The object's keys are the field names of the entity, and its value is the translated value.
+     * 
+     * @example
+     * {
+     *   "title": "Product Title",
+     *   "description": "Product Description",
+     * }
+     */
     translations: model.json(),
-    translated_field_count: model.number().default(0), // Precomputed count of translated fields for performance
+    /**
+     * Precomputed count of translated fields of a resource.
+     * Useful for optimization purposes.
+     */
+    translated_field_count: model.number().default(0),
   })
   .indexes([
     {