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:

Code
1{2  "reference_id": "prod_123",3  "reference": "product",4  "locale_code": "fr-FR",5  "translations": {6    "title": "Produit Exemple",7    "description": "Ceci est une description en français."8  }9}

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

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:

Code
1const { data: translations } = await query.graph({2  entity: "translation",3  fields: ["reference_id", "locale_code", "translations"],4  filters: {5    reference_id: "prod_123",6    locale_code: "fr-FR",7  },8})9
10console.log(translations)11// Output:12// [{13//   reference_id: "prod_123",14//   locale_code: "fr-FR",15//   translations: {16//     title: "Produit Exemple",17//     description: "Ceci est une description en français."18//   }19// }]

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:

Code
1const { data: translations } = await query.graph({2  entity: "translation",3  fields: ["reference_id", "locale_code", "translations"],4  filters: {5    reference_id: "prod_123",6    locale_code: "fr-FR",7  },8}, {9  cache: {10    enable: true,11  },12})13
14console.log(translations)15// Output:16// [{17//   reference_id: "prod_123",18//   locale_code: "fr-FR",19//   translations: {20//     title: "Produit Exemple",21//     description: "Ceci est une description en français."22//   }23// }]