asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore: TSDocs for Translation Module (#14280)

Browse Source 
* tsdocs for translation module

* fixes
This commit is contained in:
Shahed Nasser
2025-12-16 13:30:26 +02:00
committed by GitHub
parent 7b0556dd85
commit 88a3cf7172
36 changed files with 875 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

@@ -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,

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

@@ -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,

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

@@ -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 }) => {

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

@@ -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) => {

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

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

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

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

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

@@ -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
*

1
packages/core/js-sdk/src/admin/index.ts
View File

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

8
packages/core/js-sdk/src/admin/locale.ts
View File

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

14
packages/core/types/src/cart/workflows.ts
View File

@@ -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

14
packages/core/types/src/http/cart/store/payloads.ts
View File

@@ -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
}

5
packages/core/types/src/http/locale/admin/queries.ts
View File

@@ -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[]
}

2
packages/core/types/src/http/locale/common.ts
View File

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

3
packages/core/types/src/http/locale/store/responses.ts
View File

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

2
packages/core/types/src/http/order/admin/payload.ts
View File

@@ -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
/**

5
packages/core/types/src/http/store/admin/payloads.ts
View File

@@ -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[]
/**

22
packages/core/types/src/http/translations/admin/entities.ts
View File

@@ -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>

23
packages/core/types/src/http/translations/admin/queries.ts
View File

@@ -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[]
}

15
packages/core/types/src/http/translations/admin/responses.ts
View File

@@ -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
}

26
packages/core/types/src/translation/common.ts
View File

@@ -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 is the entity type (e.g., "product"), value contains the count of entities.
* Key-value pairs of entity types and their configurations.
*/
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
}

81
packages/core/types/src/translation/mutations.ts
View File

@@ -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>
}

487
packages/core/types/src/translation/service.ts
View File

@@ -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 {Context} sharedContext
* @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
* 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 {Context} sharedContext
* @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
* 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 {Context} sharedContext
* @param {FindConfig<LocaleDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
* 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 {Context} sharedContext
* @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects with IDs identifying the locales to delete.
* @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 {Context} sharedContext
* @returns {Promise<Record<string, string[]> | void>} An object with IDs of related records that were also 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 - 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 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 {Context} sharedContext
* @returns {Promise<Record<string, string[]> | void>} An object with IDs of related records that were restored.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the locale. You can pass to its `returnLinkableKeys`
* property any of the locale's relation attribute names.
* @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 {Context} sharedContext
* @param {FindConfig<TranslationDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
* 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 {Context} sharedContext
* @param {FindConfig<TranslationDTO>} config - The configurations determining how the locale is retrieved. Its properties, such as `select` or `relations`, accept the
* 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 {Context} sharedContext
* @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects with IDs identifying the translations to delete.
* @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 {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object for related entities that should be soft-deleted.
* @param {Context} sharedContext
* @returns {Promise<Record<string, string[]> | void>} An object with IDs of related records that were also soft deleted.
* @param {string | object | string[] | object[]} primaryKeyValues - The IDs or objects with IDs identifying the translations to soft delete.
* @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 - 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 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 {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore.
* @param {Context} sharedContext
* @returns {Promise<Record<string, string[]> | void>} An object with IDs of related records that were restored.
* @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 along with each of the translation. You can pass to its `returnLinkableKeys`
* property any of the translation's relation attribute names.
* @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.
* It counts translated fields at a granular level, providing both aggregated
* and per-locale breakdowns.
* This method retrieves translation statistics for the specified entities and locales.
* It's useful to understand the translation coverage of different entities across various locales.
*
* 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_variant: { count: 5 }
* product: { count }, // for example, 2 products
* product_variant: { count: variantCount },
* }
* })
* // Returns:
@@ -330,20 +704,27 @@ export interface ITranslationModuleService extends IModuleService {
): Promise<TranslationStatisticsOutput>
/**
* This method retrieves the translatable fields configuration.
* Returns a mapping of entity types to their translatable field names.
* This method retrieves the translatable fields of a resource. For example,
* product entities have translatable fields such as `title` and `description`.
*
* @param {string} entityType - Optional entity type to filter by. If not provided, returns all.
* @returns {Record<string, string[]>} A mapping of entity types to their translatable fields.
* @param {string} entityType - Name of the resource's table to get translatable fields for.
* 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
* const allFields = translationService.getTranslatableFields()
* To get translatable fields for all resources:
*
* ```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
* const productFields = translationService.getTranslatableFields("product")
* ```ts
* const productFields = translationModuleService.getTranslatableFields("product")
* // Returns: { product: ["title", "description", "subtitle", "status"] }
* ```
*/
getTranslatableFields(entityType?: string): Record<string, string[]>
}

6
packages/core/utils/src/core-flows/events.ts
View File

@@ -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