Shahed NasserandGitHub
c1a5390fc6
* docs: translation module * fix link in JS SDK * add translations user guides [WIP] * updates * fix broken link * remove mentions of default locale * change header * updates * updated user guides * handle todos * fix build error * fix lint errors
129 lines
4.2 KiB
Plaintext
129 lines
4.2 KiB
Plaintext
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](/references/translation/models/Locale) represents a language that resources can be translated into.
|
|
|
|
Its `code` property follows the [IETF BCP 47 standard](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1). 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](/references/translation/models/Translation) 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](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1) as the [Locale](#locales) 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
<Note>
|
|
|
|
To retrieve translations for the storefront, refer to the [Serve Translations in the Storefront](../storefront/page.mdx) guide.
|
|
|
|
</Note>
|
|
|
|
You can retrieve translations for a resource on the Medusa server using [Query](!docs!/learn/fundamentals/module-links/query). You can filter translations by `reference_id` and `locale_code` to get the specific translation you need.
|
|
|
|
For example:
|
|
|
|
```ts
|
|
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](../../../infrastructure-modules/caching/page.mdx) in your Medusa application, you can also cache translation queries to improve performance:
|
|
|
|
```ts
|
|
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."
|
|
// }
|
|
// }]
|
|
``` |