feat(): Translation statistics (#14299)

* chore(): Translation statistics

* chore(): improve statistics performances

* add end point to get statistics

* add tests

* Create spicy-games-unite.md

* feat(): add material and fix tests

* feat(): add translatable api

* feat(): add translatable api

* fix tests

* fix tests

* fix tests

* feedback

packages/modules/translation/src/index.ts

@@ -1,10 +1,11 @@
 import TranslationModuleService from "@services/translation-module"
 import loadDefaults from "./loaders/defaults"
+import loadConfig from "./loaders/config"
 import { Module } from "@medusajs/framework/utils"
 
 export const TRANSLATION_MODULE = "translation"
 
 export default Module(TRANSLATION_MODULE, {
   service: TranslationModuleService,
-  loaders: [loadDefaults],
+  loaders: [loadDefaults, loadConfig],
 })

packages/modules/translation/src/loaders/config.ts

@@ -0,0 +1,52 @@
+import { LoaderOptions } from "@medusajs/framework/types"
+import {
+  PRODUCT_TRANSLATABLE_FIELDS,
+  PRODUCT_VARIANT_TRANSLATABLE_FIELDS,
+} from "../utils/translatable-fields"
+import { asValue } from "awilix"
+import { TRANSLATABLE_FIELDS_CONFIG_KEY } from "@utils/constants"
+
+export default async ({
+  container,
+  options,
+}: LoaderOptions<{
+  expandedTranslatableFields: { [key: string]: string[] }
+}>): Promise<void> => {
+  const { expandedTranslatableFields } = options ?? {}
+
+  const { product, productVariant, ...others } =
+    expandedTranslatableFields ?? {}
+
+  const translatableFieldsConfig: Record<string, string[]> = {
+    product: PRODUCT_TRANSLATABLE_FIELDS,
+    product_variant: PRODUCT_VARIANT_TRANSLATABLE_FIELDS,
+  }
+
+  if (product) {
+    const translatableFields = new Set([
+      ...PRODUCT_TRANSLATABLE_FIELDS,
+      ...product,
+    ])
+    translatableFieldsConfig.product = Array.from(translatableFields)
+  }
+
+  if (productVariant) {
+    const translatableFields = new Set([
+      ...PRODUCT_VARIANT_TRANSLATABLE_FIELDS,
+      ...productVariant,
+    ])
+    translatableFieldsConfig.product_variant = Array.from(translatableFields)
+  }
+
+  if (others) {
+    Object.entries(others).forEach(([key, value]) => {
+      const translatableFields = new Set([...value])
+      translatableFieldsConfig[key] = Array.from(translatableFields)
+    })
+  }
+
+  container.register(
+    TRANSLATABLE_FIELDS_CONFIG_KEY,
+    asValue(translatableFieldsConfig)
+  )
+}

packages/modules/translation/src/migrations/.snapshot-medusa-translation.json

@@ -149,6 +149,16 @@
           "nullable": false,
           "mappedType": "json"
         },
+        "translated_field_count": {
+          "name": "translated_field_count",
+          "type": "integer",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "default": "0",
+          "mappedType": "integer"
+        },
         "created_at": {
           "name": "created_at",
           "type": "timestamptz",

packages/modules/translation/src/migrations/Migration20251215083927.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20251215083927 extends Migration {
+
+  override async up(): Promise<void> {
+    this.addSql(`alter table if exists "translation" add column if not exists "translated_field_count" integer not null default 0;`);
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table if exists "translation" drop column if exists "translated_field_count";`);
+  }
+
+}

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

@@ -6,7 +6,8 @@ const Translation = model
     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"
-    translations: model.json(), // JSON object containing translated fields, e.g., { "title": "...", "description": "..." }
+    translations: model.json(),
+    translated_field_count: model.number().default(0), // Precomputed count of translated fields for performance
   })
   .indexes([
     {

packages/modules/translation/src/services/translation-module.ts

@@ -10,20 +10,25 @@ import {
   ModulesSdkTypes,
   TranslationTypes,
 } from "@medusajs/framework/types"
+import { SqlEntityManager } from "@medusajs/framework/mikro-orm/postgresql"
 import {
   EmitEvents,
   InjectManager,
   MedusaContext,
+  MedusaError,
   MedusaService,
   normalizeLocale,
 } from "@medusajs/framework/utils"
 import Locale from "@models/locale"
 import Translation from "@models/translation"
+import { computeTranslatedFieldCount } from "@utils/compute-translated-field-count"
+import { TRANSLATABLE_FIELDS_CONFIG_KEY } from "@utils/constants"
 
 type InjectedDependencies = {
   baseRepository: DAL.RepositoryService
   translationService: ModulesSdkTypes.IMedusaInternalService<typeof Translation>
   localeService: ModulesSdkTypes.IMedusaInternalService<typeof Locale>
+  [TRANSLATABLE_FIELDS_CONFIG_KEY]: Record<string, string[]>
 }
 
 export default class TranslationModuleService
@@ -48,15 +53,19 @@ export default class TranslationModuleService
     typeof Locale
   >
 
+  private readonly translatableFieldsConfig_: Record<string, string[]>
+
   constructor({
     baseRepository,
     translationService,
     localeService,
+    translatableFieldsConfig,
   }: InjectedDependencies) {
     super(...arguments)
     this.baseRepository_ = baseRepository
     this.translationService_ = translationService
     this.localeService_ = localeService
+    this.translatableFieldsConfig_ = translatableFieldsConfig
   }
 
   static prepareFilters(
@@ -177,6 +186,10 @@ export default class TranslationModuleService
     const normalizedData = dataArray.map((translation) => ({
       ...translation,
       locale_code: normalizeLocale(translation.locale_code),
+      translated_field_count: computeTranslatedFieldCount(
+        translation.translations as Record<string, unknown>,
+        this.translatableFieldsConfig_[translation.reference]
+      ),
     }))
 
     const createdTranslations = await this.translationService_.create(
@@ -190,4 +203,193 @@ export default class TranslationModuleService
 
     return Array.isArray(data) ? serialized : serialized[0]
   }
+
+  // @ts-expect-error
+  updateTranslations(
+    data: TranslationTypes.UpdateTranslationDTO,
+    sharedContext?: Context
+  ): Promise<TranslationTypes.TranslationDTO>
+  // @ts-expect-error
+  updateTranslations(
+    data: TranslationTypes.UpdateTranslationDTO[],
+    sharedContext?: Context
+  ): Promise<TranslationTypes.TranslationDTO[]>
+
+  @InjectManager()
+  @EmitEvents()
+  // @ts-expect-error
+  async updateTranslations(
+    data:
+      | TranslationTypes.UpdateTranslationDTO
+      | TranslationTypes.UpdateTranslationDTO[],
+    @MedusaContext() sharedContext: Context = {}
+  ): Promise<
+    TranslationTypes.TranslationDTO | TranslationTypes.TranslationDTO[]
+  > {
+    const dataArray = Array.isArray(data) ? data : [data]
+
+    const updatesWithTranslations = dataArray.filter((d) => d.translations)
+
+    if (updatesWithTranslations.length) {
+      const idsNeedingReference = updatesWithTranslations
+        .filter((d) => !d.reference)
+        .map((d) => d.id)
+
+      let referenceMap: Record<string, string> = {}
+
+      if (idsNeedingReference.length) {
+        const existingTranslations = await this.translationService_.list(
+          { id: idsNeedingReference },
+          { select: ["id", "reference"] },
+          sharedContext
+        )
+        referenceMap = Object.fromEntries(
+          existingTranslations.map((t) => [t.id, t.reference])
+        )
+      }
+
+      for (const update of dataArray) {
+        if (update.translations) {
+          const reference = update.reference || referenceMap[update.id]
+          ;(
+            update as TranslationTypes.UpdateTranslationDTO & {
+              translated_field_count: number
+            }
+          ).translated_field_count = computeTranslatedFieldCount(
+            update.translations as Record<string, unknown>,
+            this.translatableFieldsConfig_[reference] || []
+          )
+        }
+      }
+    }
+
+    const updatedTranslations = await this.translationService_.update(
+      dataArray,
+      sharedContext
+    )
+
+    const serialized = await this.baseRepository_.serialize<
+      TranslationTypes.TranslationDTO[]
+    >(updatedTranslations)
+
+    return Array.isArray(data) ? serialized : serialized[0]
+  }
+
+  getTranslatableFields(entityType?: string): Record<string, string[]> {
+    if (entityType) {
+      return { [entityType]: this.translatableFieldsConfig_[entityType] }
+    }
+    return this.translatableFieldsConfig_
+  }
+
+  @InjectManager()
+  async getStatistics(
+    input: TranslationTypes.TranslationStatisticsInput,
+    @MedusaContext() sharedContext: Context = {}
+  ): Promise<TranslationTypes.TranslationStatisticsOutput> {
+    const { locales, entities } = input
+
+    if (!locales || !locales.length) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "At least one locale must be provided"
+      )
+    }
+
+    if (!entities || !Object.keys(entities).length) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "At least one entity type must be provided"
+      )
+    }
+
+    const normalizedLocales = locales.map(normalizeLocale)
+
+    const manager = (sharedContext.transactionManager ??
+      sharedContext.manager) as SqlEntityManager
+    const knex = manager.getKnex()
+
+    const result: TranslationTypes.TranslationStatisticsOutput = {}
+    const entityTypes: string[] = []
+
+    for (const entityType of Object.keys(entities)) {
+      const translatableFields = this.translatableFieldsConfig_[entityType]
+
+      if (!translatableFields || translatableFields.length === 0) {
+        result[entityType] = {
+          expected: 0,
+          translated: 0,
+          missing: 0,
+          by_locale: Object.fromEntries(
+            normalizedLocales.map((locale) => [
+              locale,
+              { expected: 0, translated: 0, missing: 0 },
+            ])
+          ),
+        }
+      } else {
+        entityTypes.push(entityType)
+      }
+    }
+
+    if (!entityTypes.length) {
+      return result
+    }
+
+    const { rows } = await knex.raw(
+      `
+      SELECT
+        reference,
+        locale_code,
+        COALESCE(SUM(translated_field_count), 0)::int AS translated_field_count
+      FROM translation
+      WHERE reference = ANY(?)
+        AND locale_code = ANY(?)
+        AND deleted_at IS NULL
+      GROUP BY reference, locale_code
+      `,
+      [entityTypes, normalizedLocales]
+    )
+
+    for (const entityType of entityTypes) {
+      const translatableFields = this.translatableFieldsConfig_[entityType]
+      const fieldsPerEntity = translatableFields.length
+      const entityCount = entities[entityType].count
+      const expectedPerLocale = entityCount * fieldsPerEntity
+
+      result[entityType] = {
+        expected: expectedPerLocale * normalizedLocales.length,
+        translated: 0,
+        missing: expectedPerLocale * normalizedLocales.length,
+        by_locale: Object.fromEntries(
+          normalizedLocales.map((locale) => [
+            locale,
+            {
+              expected: expectedPerLocale,
+              translated: 0,
+              missing: expectedPerLocale,
+            },
+          ])
+        ),
+      }
+    }
+
+    for (const row of rows) {
+      const entityType = row.reference
+      const localeCode = row.locale_code
+      const translatedCount = parseInt(row.translated_field_count, 10) || 0
+
+      result[entityType].by_locale[localeCode].translated = translatedCount
+      result[entityType].by_locale[localeCode].missing =
+        result[entityType].by_locale[localeCode].expected - translatedCount
+      result[entityType].translated += translatedCount
+    }
+
+    for (const entityType of entityTypes) {
+      result[entityType].missing =
+        result[entityType].expected - result[entityType].translated
+    }
+
+    return result
+  }
 }

packages/modules/translation/src/utils/compute-translated-field-count.ts

@@ -0,0 +1,23 @@
+/**
+ * Computes the count of translated fields based on the translatable fields configuration.
+ * Only counts fields that are:
+ * 1. In the translatableFields array for the entity type
+ * 2. Have a non-null, non-empty value in the translations object
+ *
+ * @param translations - The translations JSON object from the translation record
+ * @param translatableFields - Array of field names that are translatable for this entity type
+ * @returns The count of translated fields
+ */
+export function computeTranslatedFieldCount(
+  translations: Record<string, unknown> | undefined | null,
+  translatableFields: string[] | undefined | null
+): number {
+  if (!translations || !translatableFields?.length) {
+    return 0
+  }
+
+  return translatableFields.filter((field) => {
+    const value = translations[field]
+    return value != null && value !== "" && value !== "null"
+  }).length
+}

packages/modules/translation/src/utils/constants.ts

@@ -0,0 +1 @@
+export const TRANSLATABLE_FIELDS_CONFIG_KEY = "translatableFieldsConfig"

packages/modules/translation/src/utils/translatable-fields.ts

@@ -0,0 +1,9 @@
+export const PRODUCT_TRANSLATABLE_FIELDS = [
+  "title",
+  "description",
+  "material",
+  "subtitle",
+  "status",
+]
+
+export const PRODUCT_VARIANT_TRANSLATABLE_FIELDS = ["title", "material"]