asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: translation module (#14271)

Browse Source 
* 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
This commit is contained in:
Shahed Nasser
2025-12-17 13:07:43 +02:00
committed by GitHub
parent 1743ed7f04
commit c1a5390fc6
133 changed files with 21304 additions and 1661 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/cart/concepts/page.mdx
+14
View File
@@ -18,6 +18,20 @@ A cart holds information about:
- The payment method and information necessary to complete the purchase.
- These are stored and handled by the [Payment Module](../../payment/page.mdx).
### Cart Locale
<Note>
Cart locale is available starting [Medusa v2.12.3](https://github.com/medusajs/medusa/releases/tag/v2.12.3).
</Note>
The `Cart` data model has a `locale` property that indicates the locale of the cart. This locale is in the [IETF BCP 47 standard](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1) format, such as `en-US` for American English or `fr-FR` for French (France).
When creating a cart, you can set the `locale` property to specify the desired locale for the cart. The information of the items in the cart, such as product titles and descriptions, will be displayed in the specified locale if translations are available.
Refer to the [Translation Module](../../translation/page.mdx) to learn more about how translations and locales work.
---
## Line Items
www/apps/resources/app/commerce-modules/order/concepts/page.mdx
+16
View File
@@ -17,6 +17,22 @@ An order holds information about:
- This is stored and handled by the [Customer Module](../../customer/page.mdx).
- Payment and shipping information
## Order Locale
<Note>
Order locale is available starting [Medusa v2.12.3](https://github.com/medusajs/medusa/releases/tag/v2.12.3).
</Note>
The `Order` data model has a `locale` property that indicates the locale of the order. This locale is in the [IETF BCP 47 standard](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1) format, such as `en-US` for American English or `fr-FR` for French (France).
When an order is created from a cart or a draft order, the order inherits their locale. This ensures that all item details in the order, such as product titles and descriptions, are presented in the correct language if translations are available.
When order items are changed through an edit, claim, or exchange, the new items added to the order will also have their details in the order's locale if translations are available.
You can also edit an order's locale using the [Update Order](!api!/admin#orders_postordersid) API route.
---
## Order Items
www/apps/resources/app/commerce-modules/order/draft-orders/page.mdx
+6
View File
@@ -102,6 +102,12 @@ Similar to regular orders, draft orders can be [edited](../edit/page.mdx), allow
When the order edit is confirmed on the draft order, the changes are applied directly to the draft order and its [version](../order-versioning/page.mdx) is incremented.
### Draft Order Locale
A draft order's `locale` can be set and updated before converting it to a regular order. All item details in the draft order, such as product titles and descriptions, will be presented in the correct language if translations are available.
When the draft order is converted to a regular order, it retains its `locale` property. The details of the order items will remain in the specified locale.
### Converting Draft Orders to Regular Orders
Once a draft order is finalized and ready for processing, it can be converted to a regular order. This involves:
www/apps/resources/app/commerce-modules/page.mdx
+14 -4
View File
@@ -1,4 +1,4 @@
import { CardList } from "docs-ui"
import { CardList, Card } from "docs-ui"
export const metadata = {
title: `Commerce Modules`,
@@ -85,12 +85,22 @@ A Commerce Module also defines data models, representing tables in the database.
href: "/commerce-modules/tax"
},
{
title: "User Module",
href: "/commerce-modules/user"
}
title: "Translation Module",
href: "/commerce-modules/translation",
badge: {
children: "Beta",
variant: "blue"
}
},
]}
/>
<Card
title="User Module"
href="/commerce-modules/user"
className="my-1"
/>
---
## How to Use Modules
www/apps/resources/app/commerce-modules/product/links-to-other-modules/page.mdx
+182 -1
View File
@@ -8,7 +8,7 @@ products:
- sales channel
---
import { CodeTabs, CodeTab, Table } from "docs-ui"
import { CodeTabs, CodeTab, Table, Prerequisites } from "docs-ui"
export const metadata = {
title: `Links between Product Module and Other Modules`,
@@ -130,6 +130,118 @@ Read-only links are used to query data across modules, but the relations aren't
[Learn more](#sales-channel-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Product](/references/product/models/Product)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductVariant](/references/product/models/ProductVariant)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductCategory](/references/product/models/ProductCategory)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductCollection](/references/product/models/ProductCollection)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductTag](/references/product/models/ProductTag)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductType](/references/product/models/ProductType)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductOption](/references/product/models/ProductOption)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductOptionValue](/references/product/models/ProductOptionValue)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
@@ -624,3 +736,72 @@ createRemoteLinkStep({
</CodeTab>
</CodeTabs>
---
## Translation Module
<Prerequisites
items={[
{
title: "Translation Module",
link: "/commerce-modules/translation",
},
]}
/>
Medusa defines read-only links from several data models in the Product Module to the [Translation](/references/translation/models/Translation) data model in the [Translation Module](../../translation/page.mdx):
- `Product` (one-to-many) to `Translation`, and vice versa.
- `ProductVariant` (one-to-many) to `Translation`. You can only retrieve the translations of a product variant, and not the other way around.
- `ProductCategory` (one-to-many) to `Translation`. You can only retrieve the translations of a product category, and not the other way around.
- `ProductCollection` (one-to-many) to `Translation`. You can only retrieve the translations of a product collection, and not the other way around.
- `ProductTag` (one-to-many) to `Translation`. You can only retrieve the translations of a product tag, and not the other way around.
- `ProductType` (one-to-many) to `Translation`. You can only retrieve the translations of a product type, and not the other way around.
- `ProductOption` (one-to-many) to `Translation`. You can only retrieve the translations of a product option, and not the other way around.
- `ProductOptionValue` (one-to-many) to `Translation`. You can only retrieve the translations of a product option value, and not the other way around.
### Retrieve with Query
To retrieve the translations of a product with [Query](!docs!/learn/fundamentals/module-links/query), pass `translations.*` in `fields`:
<Note>
You can pass the `translations.*` field when querying any of the above-mentioned data models to retrieve their associated translations.
</Note>
<CodeTabs group="relation-query">
<CodeTab label="query.graph" value="method">
```ts
const { data: products } = await query.graph({
entity: "product",
fields: [
"translations.*",
],
})
// products[0].translations
```
</CodeTab>
<CodeTab label="useQueryGraphStep" value="step">
```ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
const { data: products } = useQueryGraphStep({
entity: "product",
fields: [
"translations.*",
],
})
// products[0].translations
```
</CodeTab>
</CodeTabs>
www/apps/resources/app/commerce-modules/store/links-to-other-modules/page.mdx
+74 -3
View File
@@ -3,7 +3,7 @@ products:
- currency
---
import { CodeTabs, CodeTab, Table } from "docs-ui"
import { CodeTabs, CodeTab, Table, Prerequisites } from "docs-ui"
export const metadata = {
title: `Links between Store Module and Other Modules`,
@@ -55,6 +55,20 @@ Read-only links are used to query data across modules, but the relations aren't
[Learn more](#currency-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[StoreLocale](/references/store/models/StoreLocale)
</Table.Cell>
<Table.Cell>
[Locale](/references/translation/models/Locale) in [Translation Module](../../translation/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - has many
</Table.Cell>
<Table.Cell>
[Learn more](#translation-module)
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
@@ -62,9 +76,9 @@ Read-only links are used to query data across modules, but the relations aren't
## Currency Module
The Store Module has a `Currency` data model that stores the supported currencies of a store. However, these currencies don't hold all the details of a currency, such as its name or symbol.
The Store Module has a `StoreCurrency` data model that stores the supported currencies of a store. However, these currencies don't hold all the details of a currency, such as its name or symbol.
Instead, Medusa defines a read-only link between the [Currency Module](../../currency/page.mdx)'s `Currency` data model and the Store Module's `StoreCurrency` data model. This means you can retrieve the details of a store's supported currencies, but you don't manage the links in a pivot table in the database. The currencies of a store are determined by the `currency_code` of the [Currency](/references/store/models/StoreCurrency) data model in the Store Module (not in the Currency Module).
Instead, Medusa defines a read-only link from the Store Module's `StoreCurrency` data model to the [Currency Module](../../currency/page.mdx)'s `Currency` data model. This means you can retrieve the details of a store's supported currencies, but you don't manage the links in a pivot table in the database.
### Retrieve with Query
@@ -104,3 +118,60 @@ const { data: stores } = useQueryGraphStep({
</CodeTab>
</CodeTabs>
---
## Translation Module
<Prerequisites
items={[
{
text: "Translation Module Configured",
link: "/commerce-modules/translation#configure-translation-module",
}
]}
/>
The Store Module has a `StoreLocale` data model that stores the supported locales of a store. However, these locales don't hold all the details of a locale, such as its name.
Instead, Medusa defines a read-only link from the Store Module's `StoreLocale` data model to the [Translation Module](../../translation/page.mdx)'s `Locale` data model. This means you can retrieve the details of a store's supported locales, but you don't manage the links in a pivot table in the database.
### Retrieve with Query
To retrieve the details of a store's locales with [Query](!docs!/learn/fundamentals/module-links/query), pass `supported_locales.locale.*` in `fields`:
<CodeTabs group="relation-query">
<CodeTab label="query.graph" value="method">
```ts
const { data: stores } = await query.graph({
entity: "store",
fields: [
"supported_locales.locale.*",
],
})
// stores[0].supported_locales[0].locale
```
</CodeTab>
<CodeTab label="useQueryGraphStep" value="step">
```ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
const { data: stores } = useQueryGraphStep({
entity: "store",
fields: [
"supported_locales.locale.*",
],
})
// stores[0].supported_locales[0].locale
```
</CodeTab>
</CodeTabs>
www/apps/resources/app/commerce-modules/store/locales/page.mdx
+34
View File
@@ -0,0 +1,34 @@
import { Prerequisites } from "docs-ui"
export const metadata = {
title: `Store Locales`,
}
# {metadata.title}
In this guide, you'll learn about locales defined in the Store Module.
<Prerequisites
items={[
{
text: "Medusa v2.12.3 or later",
link: "https://github.com/medusajs/medusa/releases/tag/v2.12.3",
},
]}
/>
<Note>
While the Store Module allows you to manage the locales for your store, the actual locale data and translations are managed by the [Translation Module](../../translation/page.mdx).
</Note>
## Supported Locales
The Store Module has a [StoreLocale](/references/store/models/StoreLocale) data model that represents the locales supported by your store. It has a `locale_code` property that 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).
`StoreLocale` belongs to the [Store](/references/store/models/Store) data model, which has a `supported_locales` property that lists all the locales available in your store.
For example, if your store supports English (United States) and French (France), you'll have two `StoreLocale` records with the locale codes `en-US` and `fr-FR`.
![Diagram illustrating the relationship between the Store and StoreLocale data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1765371144/Medusa%20Resources/store-locale_ckanv4.jpg)
www/apps/resources/app/commerce-modules/translation/concepts/page.mdx
+129
View File
@@ -0,0 +1,129 @@
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."
// }
// }]
```
www/apps/resources/app/commerce-modules/translation/js-sdk/page.mdx
+15
View File
@@ -0,0 +1,15 @@
import { ChildDocs } from "docs-ui"
export const metadata = {
title: `Translation JS SDK Methods`,
}
# {metadata.title}
The [JS SDK](../../../js-sdk/page.mdx) allows you to send requests to the Medusa server application from your client applications, such as a storefront or the Medusa Admin dashboard.
Use the following methods or properties to send requests to Translation related API routes in your Medusa application. They are provided by the `@medusajs/js-sdk` package.
The following links will take you to the reference documentation for the [JS SDK](../../../js-sdk/page.mdx).
<ChildDocs type="item" />
www/apps/resources/app/commerce-modules/translation/links-to-other-modules/page.mdx
+370
View File
@@ -0,0 +1,370 @@
---
products:
- product
- store
---
import { CodeTabs, CodeTab, Table } from "docs-ui"
export const metadata = {
title: `Links between Translation Module and Other Modules`,
}
# {metadata.title}
This document showcases the module links that Medusa defines between the Translation Module and other Commerce Modules.
## Summary
Medusa defines the following links between the Translation Module and other Commerce Modules:
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>
First Data Model
</Table.HeaderCell>
<Table.HeaderCell>
Second Data Model
</Table.HeaderCell>
<Table.HeaderCell>
Type
</Table.HeaderCell>
<Table.HeaderCell>
Description
</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
[Product](/references/product/models/Product) in [Product Module](../../product/page.mdx)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#product-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductVariant](/references/product/models/ProductVariant) in [Product Module](../../product/page.mdx)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#product-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductCategory](/references/product/models/ProductCategory) in [Product Module](../../product/page.mdx)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#product-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductCollection](/references/product/models/ProductCollection) in [Product Module](../../product/page.mdx)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#product-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductTag](/references/product/models/ProductTag) in [Product Module](../../product/page.mdx)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#product-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductType](/references/product/models/ProductType) in [Product Module](../../product/page.mdx)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#product-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductOption](/references/product/models/ProductOption) in [Product Module](../../product/page.mdx)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#product-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductOptionValue](/references/product/models/ProductOptionValue) in [Product Module](../../product/page.mdx)
</Table.Cell>
<Table.Cell>
[Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
Read-only - one-to-many
</Table.Cell>
<Table.Cell>
[Learn more](#product-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[StoreLocale](/references/store/models/StoreLocale) in [Store Module](../../store/page.mdx)
</Table.Cell>
<Table.Cell>
[Locale](/references/translation/models/Locale)
</Table.Cell>
<Table.Cell>
Read-only - has many
</Table.Cell>
<Table.Cell>
[Learn more](#store-module)
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Product Module
Medusa defines the following read-only links between the Translation and Product Modules:
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>
Data Model
</Table.HeaderCell>
<Table.HeaderCell>
Link Type
</Table.HeaderCell>
<Table.HeaderCell>
Description
</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
[Product](/references/product/models/Product) \<-\> [Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
One-to-many (bidirectional)
</Table.Cell>
<Table.Cell>
Retrieve translations associated with a product and vice versa.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductVariant](/references/product/models/ProductVariant) -> [Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
One-to-many (read-only)
</Table.Cell>
<Table.Cell>
Retrieve translations of a product variant only.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductCategory](/references/product/models/ProductCategory) -> [Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
One-to-many (read-only)
</Table.Cell>
<Table.Cell>
Retrieve translations of a product category only.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductCollection](/references/product/models/ProductCollection) -> [Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
One-to-many (read-only)
</Table.Cell>
<Table.Cell>
Retrieve translations of a product collection only.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductTag](/references/product/models/ProductTag) -> [Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
One-to-many (read-only)
</Table.Cell>
<Table.Cell>
Retrieve translations of a product tag only.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductType](/references/product/models/ProductType) -> [Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
One-to-many (read-only)
</Table.Cell>
<Table.Cell>
Retrieve translations of a product type only.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductOption](/references/product/models/ProductOption) -> [Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
One-to-many (read-only)
</Table.Cell>
<Table.Cell>
Retrieve translations of a product option only.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ProductOptionValue](/references/product/models/ProductOptionValue) -> [Translation](/references/translation/models/Translation)
</Table.Cell>
<Table.Cell>
One-to-many (read-only)
</Table.Cell>
<Table.Cell>
Retrieve translations of a product option value only.
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
### Retrieve with Query
To retrieve the translations of a product with [Query](!docs!/learn/fundamentals/module-links/query), pass `translations.*` in `fields`:
<Note>
You can pass the `translations.*` field when querying any of the above-mentioned data models to retrieve their associated translations.
</Note>
<CodeTabs group="relation-query">
<CodeTab label="query.graph" value="method">
```ts
const { data: products } = await query.graph({
entity: "product",
fields: [
"translations.*",
],
})
// products[0].translations
```
</CodeTab>
<CodeTab label="useQueryGraphStep" value="step">
```ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
const { data: products } = useQueryGraphStep({
entity: "product",
fields: [
"translations.*",
],
})
// products[0].translations
```
</CodeTab>
</CodeTabs>
---
## Store Module
The [Store Module](../../store/page.mdx) has a `StoreLocale` data model that stores the supported locales of a store. However, these locales don't hold all the details of a locale, such as its name.
Instead, Medusa defines a read-only link from the Store Module's `StoreLocale` data model to the Translation Module's `Locale` data model. This means you can retrieve the details of a store's supported locales, but you don't manage the links in a pivot table in the database.
### Retrieve with Query
To retrieve the details of a store's locales with [Query](!docs!/learn/fundamentals/module-links/query), pass `supported_locales.locale.*` in `fields`:
<CodeTabs group="relation-query">
<CodeTab label="query.graph" value="method">
```ts
const { data: stores } = await query.graph({
entity: "store",
fields: [
"supported_locales.locale.*",
],
})
// stores[0].supported_locales[0].locale
```
</CodeTab>
<CodeTab label="useQueryGraphStep" value="step">
```ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
const { data: stores } = useQueryGraphStep({
entity: "store",
fields: [
"supported_locales.locale.*",
],
})
// stores[0].supported_locales[0].locale
```
</CodeTab>
</CodeTabs>
www/apps/resources/app/commerce-modules/translation/page.mdx
+222
View File
@@ -0,0 +1,222 @@
---
generate_toc: true
---
import { CodeTabs, CodeTab, ChildDocs, Prerequisites } from "docs-ui"
export const metadata = {
title: `Translation Module`,
}
# {metadata.title}
In this section of the documentation, you will find resources to learn more about the Translation Module and how to use it in your application.
<Prerequisites
items={[
{
text: "Medusa v2.12.3 or later",
link: "https://github.com/medusajs/medusa/releases/tag/v2.12.3"
},
{
text: "Translation Feature Flag Enabled",
link: "#"
}
]}
/>
<Note title="Looking for no-code docs?">
Refer to the [Medusa Admin User Guide](!user-guide!/settings/translations) to learn how to manage translations in the dashboard.
</Note>
Medusa has translation features available out-of-the-box through the Translation Module. A [module](!docs!/learn/fundamentals/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features is provided in Commerce Modules, such as the Translation Module.
<Note>
Refer to the [Module Isolation](!docs!/learn/fundamentals/modules/isolation) guide to learn more about why modules are isolated.
</Note>
## Translation Features
- [Translation and Locale Management](./concepts/page.mdx): Manage locales and add translations for different resources in your store.
- [Multi-Language Support](./storefront/page.mdx): Manage and serve resources like products in multiple languages to cater to a diverse customer base.
---
## Configure Translation Module
The Translation Module is currently behind a feature flag. To use it in your Medusa application, add it to the `modules` array and enable the `translation` feature flag.
In your `medusa-config.ts` file, add the Translation Module to the `modules` array and enable the `translation` feature flag:
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
// other modules...
{
resolve: "@medusajs/medusa/translation",
},
],
featureFlags: {
translation: true,
},
})
```
Then, run the following command to make the necessary database changes for the Translation Module:
```bash
npx medusa db:migrate
```
You can then use the Translation Module in your Medusa application.
---
## How to Use the Translation Module
In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](!docs!/learn/fundamentals/workflows), which is a special function composed of a series of steps that guarantees data consistency and a reliable rollback mechanism.
You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
For example:
export const highlights = [
["12", "Modules.TRANSLATION", "Resolve the module in a step."]
]
```ts title="src/workflows/create-translation.ts" highlights={highlights}
import {
createWorkflow,
WorkflowResponse,
createStep,
StepResponse,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const createTranslationStep = createStep(
"create-translation",
async ({}, { container }) => {
const translationModuleService = container.resolve(Modules.TRANSLATION)
const translation = await translationModuleService.createTranslations({
reference_id: "product_123",
reference: "product",
locale_code: "fr-FR",
translations: {
title: "Produit Exemple",
description: "Ceci est une description en français.",
},
})
return new StepResponse({ translation }, translation.id)
},
async (translationId, { container }) => {
const translationModuleService = container.resolve(Modules.TRANSLATION)
await translationModuleService.deleteTranslations([translationId])
}
)
export const createTranslationWorkflow = createWorkflow(
"create-translation",
() => {
const { translation } = createTranslationStep()
return new WorkflowResponse({
translation,
})
}
)
```
You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
<CodeTabs group="resource-types">
<CodeTab label="API Route" value="api-route">
```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
import { createTranslationWorkflow } from "../../workflows/create-translation"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
) {
const { result } = await createTranslationWorkflow(req.scope)
.run()
res.send(result)
}
```
</CodeTab>
<CodeTab label="Subscriber" value="subscriber">
```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/framework"
import { createTranslationWorkflow } from "../workflows/create-translation"
export default async function handleUserCreated({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const { result } = await createTranslationWorkflow(container)
.run()
console.log(result)
}
export const config: SubscriberConfig = {
event: "user.created",
}
```
</CodeTab>
<CodeTab label="Scheduled Job" value="scheduled-job">
```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
import { MedusaContainer } from "@medusajs/framework/types"
import { createTranslationWorkflow } from "../workflows/create-translation"
export default async function myCustomJob(
container: MedusaContainer
) {
const { result } = await createTranslationWorkflow(container)
.run()
console.log(result)
}
export const config = {
name: "run-once-a-day",
schedule: `0 0 * * *`,
}
```
</CodeTab>
</CodeTabs>
Refer to the [Workflows](!docs!/learn/fundamentals/workflows) documentation to learn more.
---
## Supported Module Translations
The Translation Module currently supports translations for all data models in the [Product Module](../product/page.mdx), including products, product variants, and categories.
Future versions of the Translation Module will include support for all Commerce Modules, as well as custom modules.
---
<CommerceModuleSections />
www/apps/resources/app/commerce-modules/translation/storefront/page.mdx
+114
View File
@@ -0,0 +1,114 @@
---
products:
- store
- product
- cart
---
import { Prerequisites, CodeTabs } from "docs-ui"
export const metadata = {
title: `Serve Translations in the Storefront`,
}
# {metadata.title}
In this guide, you’ll learn how to use locales and serve translated content in your storefront application in your Medusa application.
<Prerequisites
items={[
{
text: "Translation Module Configured",
link: "/commerce-modules/translation#configure-translation-module",
},
]}
/>
## Fetch Store Locales
You can retrieve the list of locales available in your store using the [List Locales Store API route](!api!/store#locales_getlocales). You can display this list to customers, allowing them to select their preferred language.
For example, to fetch the list of locales, send a `GET` request to the following endpoint:
```bash
curl "http://localhost:9000/store/locales" \
-H 'x-publishable-api-key: {your_publishable_api_key}'
```
Learn more in the [Localization](../../../storefront-development/localization/page.mdx) storefront guide.
<Note title="Tip">
You must pass a publishable API key in the request header to store API routes. Learn more in the [Store API reference](!api!/store#publishable-api-key).
</Note>
---
## Retrieve Translations for Resources
Currently, you can retrieve translations using the [Store API routes](!api!/store) for product-related resources, such as products, product variants, and categories. Future releases will expand translation support to additional resources.
Medusa determines the locale for the request in the following order of priority:
- The `locale` query parameter in the API request.
- The `x-medusa-locale` header in the API request.
If translations aren't available for the selected locale, or no locale is selected, the original content stored in the resource's data model is returned.
For example:
```bash
curl "http://localhost:9000/store/products?locale=fr-FR" \
-H 'x-publishable-api-key: {your_publishable_api_key}'
```
This returns the list of products with their French (France) translations if available:
```json
{
"products": [
{
"id": "prod_123",
"title": "Produit Exemple",
"description": "Ceci est une description en français.",
// other product fields...
},
// other products...
]
}
```
Learn more in the [List Products](../../../storefront-development/products/list/page.mdx#retrieve-translations-for-products) storefront guide.
---
## Set a Cart's Locale
A cart can have a locale, which determines the language of the item contents. You can set the locale when creating the cart and update it if the user changes their language preference.
For example, when creating a cart, set the `locale` property in the request body:
```bash
curl -X POST "http://localhost:9000/store/carts" \
-H 'x-publishable-api-key: {your_publishable_api_key}' \
-H "Content-Type: application/json" \
-d '{
// other cart properties...
"locale": "fr-FR"
}'
```
This creates a cart with the French (France) locale. When you add items to the cart, their titles and descriptions are displayed in French if translations are available.
If you don't specify a locale when creating the cart, the original product content is used for the items in the cart.
Learn more in the [Create Cart](../../../storefront-development/cart/create/page.mdx) and [Update Cart](../../../storefront-development/cart/update/page.mdx) storefront guides.
---
## Locale of Placed Order
When a cart is completed and an order is placed, the locale of the cart is copied to the order. The content of items in the order is displayed in the locale that was set in the cart.
This ensures that customers see order details in their preferred language.
www/apps/resources/app/commerce-modules/translation/workflows/page.mdx
+15
View File
@@ -0,0 +1,15 @@
import { ChildDocs } from "docs-ui"
export const metadata = {
title: `Translation Workflows`,
}
# {metadata.title}
[Workflows](!docs!/learn/fundamentals/workflows) are a series of queries and actions, called steps, that complete a task. By using workflows, you benefit from features like data consistency and a reliable roll-back mechanism.
When building your customizations, it's highly recommended to re-use Medusa's existing workflows and steps where possible. The following workflows and steps allow you to manage Translations and use their features in your Medusa application. They are provided by the `@medusajs/medusa/core-flows` package.
The following links will take you to the reference documentation for [Medusa's Core Workflows](/medusa-workflows-reference).
<ChildDocs type="item" defaultItemsPerRow={2} />