import { Prerequisites } from "docs-ui"

export const metadata = { title: Translation Concepts, }

{metadata.title}

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

<Prerequisites items={[ { text: "Translation Module Configured", link: "/commerce-modules/translation#configure-translation-module", }, ]} />

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.

Retrieve Translations in Medusa

To retrieve translations for the storefront, refer to the Serve Translations in the Storefront guide.

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."
//   }
// }]