Translation Concepts

In this guide, you'll learn about the key concepts related to the Translation Module, including locales and translations.

Locales#

The Locale data model represents a language that resources can be translated into.

Its code property follows the IETF BCP 47 standard. For example, en-US represents American English, while fr-FR represents French (France).

Locales are automatically populated in your Medusa application the first time the Translation Module is used.

Default Locale#

The Translation Module doesn't enforce a default locale. If a resource doesn't have a translation in the requested locale, it will fall back to the original value stored in the resource's data model.

Translations#

The Translation data model represents a translated value for a specific resource in a specific locale.

The data model has the following properties to associate the translation with the resource:

• reference_id: The ID of the resource being translated (for example, the ID of the product being translated).
• reference: The name of the table where the resource is stored (for example, product when translating a product).

The locale of the translation is indicated by the locale_code property, which follows the same IETF BCP 47 standard as the Locale data model.

A resource may have only one translation per locale. For example, a product can have only one translation in fr-FR and another translation in es-ES.

The actual translated values are stored in the translations property, which is a JSON object where each key represents a field of the resource being translated, and the value is the translated text.

For example, a translation for a product to French (fr-FR) may look like this:

{
  "reference_id": "prod_123",
  "reference": "product",
  "locale_code": "fr-FR",
  "translations": {
    "title": "Produit Exemple",
    "description": "Ceci est une description en français."
  }
}

Each key in the translations object corresponds to a property in the product resource, such as title and description, with their respective translated values.

Update Translations#

When you update a translation, for example, with the Translation Module's updateTranslations method or the batchTranslationsWorkflow, Medusa merges the translations object you pass into the existing translations object. It doesn't replace the entire object.

So, the update only changes the keys you pass. Keys that you omit keep their existing translated values.

For example, if a translation has the title and description keys, the following update only changes the title, and keeps the description as is:

await translationModuleService.updateTranslations({
  id: "trans_123",
  translations: {
    title: "Nouveau titre",
  },
})

To remove the translated value of a field, set its key to null:

await translationModuleService.updateTranslations({
  id: "trans_123",
  translations: {
    description: null,
  },
})

Medusa ignores translated values that are null or empty, and falls back to the original value stored in the resource's data model.

Retrieve Translations in Medusa#

You can retrieve translations for a resource on the Medusa server using Query. You can filter translations by reference_id and locale_code to get the specific translation you need.

For example:

const { data: translations } = await query.graph({
  entity: "translation",
  fields: ["reference_id", "locale_code", "translations"],
  filters: {
    reference_id: "prod_123",
    locale_code: "fr-FR",
  },
})

console.log(translations)
// Output:
// [{
//   reference_id: "prod_123",
//   locale_code: "fr-FR",
//   translations: {
//     title: "Produit Exemple",
//     description: "Ceci est une description en français."
//   }
// }]

In this example, you retrieve the translation records of a product with the ID prod_123 in French (fr-FR).

If you've enabled the Caching Module in your Medusa application, you can also cache translation queries to improve performance:

const { data: translations } = await query.graph({
  entity: "translation",
  fields: ["reference_id", "locale_code", "translations"],
  filters: {
    reference_id: "prod_123",
    locale_code: "fr-FR",
  },
}, {
  cache: {
    enable: true,
  },
})

console.log(translations)
// Output:
// [{
//   reference_id: "prod_123",
//   locale_code: "fr-FR",
//   translations: {
//     title: "Produit Exemple",
//     description: "Ceci est une description en français."
//   }
// }]