EDU-10819 - Feedback #3316 - Improvement #2265
Conversation
Preview LinksOpen this URL to set up the portal with this branch changes. You can now access the edited pages with the following URLs: |
Navigation Preview LinkNo changes detected in the navigation.json file |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
markdownlint
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Query variables"]
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Mutation"]
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Query variables"]
| } | ||
| ``` | ||
| 2. Then, to fill in the `Query Variables` box, you must provide the following parameters: |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1]
| } | ||
| ``` | ||
|
|
||
| 3. After adjusting your query, click the play button to run it. The expected response is the translated message in the target locale. |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 3; Style: 1/1/1]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 5; Style: 1/2/3]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD029/ol-prefix Ordered list item prefix [Expected: 2; Actual: 6; Style: 1/2/3]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Mutation"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Query variables"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Mutation"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Query variables"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Mutation"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Query variables"]
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Mutation"]
Documentation feedback for docs/guides/vtex-io/Storefront-Guides/vtex-io-multi-language-stores/catalog-internationalization.mdGeneral FeedbackThe guide provides a detailed walkthrough of translating catalog content using the Actionable Feedback
Suggested Revision---
title: "Translating Catalog Content"
excerpt: "Learn how to overwrite automatic message translations in the catalog for specific store content."
slug: "translating-catalog-content"
hidden: false
createdAt: "2020-08-31T17:18:54.238Z"
updatedAt: "2025-10-29T19:24:24.450Z"
---
In this guide, you will learn how to overwrite automatic message translations from the catalog, such as a product name or a product description, with more specific and representative content for your store. By the end of this guide, you will be able to use the `catalog-graphql` app to ensure your catalog content accurately reflects your brand across different languages.
Catalog messages are translatable text strings related to a store catalog, stored as external data in the [Catalog API](https://developers.vtex.com/docs/api-reference/catalog-api#overview), which manages a store's sales channels, categories, brands, products, SKUs, and specifications. The following catalog settings can be automatically translated based on the user locale:
- **[Category](https://help.vtex.com/en/tutorial/category-registration-fields--5Z7RrvW41yumyQCmk2iqoG):** Name, keywords (similar words), page title (tag title), meta tag description, and the URL slug (cross-border stores only).
- **[Brand](https://help.vtex.com/en/tutorial/brand-registration-fields--37Ky7lTbEkiWIAYA80EMyI):** Name, keywords (similar words), page title (tag title), meta tag description, and the URL slug (cross-border stores only).
- **[Product](https://help.vtex.com/en/tutorial/product-registration-fields--4dYXWIK3zyS8IceKkQseke):** Name, keywords (similar words), page title (tag title), description, short description, meta tag description, and URL slug (cross-border stores only).
- **[SKU](https://help.vtex.com/en/tutorial/sku-registration-fields--21DDItuEQc6mseiW8EakcY):** Name.
- **[SKU or product specification](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/2NQoBv8m4Yz3oQaLgDRagP):** Name, description, and values.
Considering literal translations and cultural factors, you may want to overwrite automatic translations with content that is specific and representative of your store. This can be done through the `catalog-graphql` app, which is the GraphQL interface of the Catalog API.
## Instructions
### Step 1 - Install the `admin-graphql-ide` app
Install the `[email protected]` app using your terminal. This app provides the GraphQL IDE interface needed to interact with the Catalog API.
### Step 2 - Open the GraphQL IDE
In the VTEX Admin, go to **Store Settings > Storefront > GraphQL IDE**. This will open the GraphQL IDE where you can execute queries and mutations.
### Step 3 - Select the `catalog-graphql` app
From the dropdown list in the GraphQL IDE, choose the `vtex.catalog-graphql` app. This specifies that you will be working with the Catalog API.
### Step 4 - Access Query Variables
Click **Query variables** at the bottom of the page to open the section where you will input the variables for your GraphQL mutations.
### Step 5 - Define the Translation
Based on the catalog entity you want to translate (category, brand, product, SKU, or specification), complete the main text box with the appropriate mutation command and the _Query variables_ section with the desired translations.
### Step 6 - Translate Category
To translate a category, follow these steps:
#### Mutation
Complete the main text box with the following mutation command:
```gql
mutation translate($args:CategoryInputTranslation, $locale:Locale){
translateCategory(category:$args,locale:$locale)
}
```
#### Query variables
Complete the _Query variables_ section with the desired translations for each parameter.
```json
{
"args":{
"id": "3",
"name": "Eletrônicos",
"title": "Casa - Eletrônicos",
"description": "Esta é a descrição da categoria Eletrônicos",
"keywords": [
"eletronicos",
"utensílios"
],
"linkId": "eletronicos"
},
"locale": "pt-BR"
}
```
- `id`: Category ID. Every category in your store has a unique ID, which can be found under Catalog > Categories in the VTEX Admin.
- `name`: Category name.
- `title`: Meta title for the category page.
- `description`: Detailed description of the category.
- `keywords`: Object containing the translations of **each** similar word for the category.
- `linkId`: The `textLink` (must **not** be translated unless your store is cross-border).
- `locale`: Target translation locale.
> ℹ️ If you have a cross-border store, the `linkId` serves as the category URL slug. The [Rewriter](https://developers.vtex.com/docs/guides/rewriter) app will automatically create an alias using the translated slug for each target locale and store it in the `resolveAs` field for that locale's internal route. For example, a category with the slug `eletronics` at `http://{storename}.com/us/eletronics/d` could have the translated slug `eletronicos` for the `pt-BR` binding, as in `http://{storename}.com/br/eletronicos/d`.
### Step 7 - Translate Brand
To translate a brand, follow these steps:
#### Mutation
Complete the main text box with the following mutation command:
```gql
mutation translate($args:BrandInputTranslation, $locale:Locale){
translateBrand(brand:$args,locale:$locale)
}
```
#### Query variables
Complete the _Query variables_ section with the desired translations for each parameter.
```json
{
"args":{
"id": "2000057",
"name": "Calvin Klein",
"text": "Esta é uma descrição da marca.",
"siteTitle": "Calvin Klein",
"keywords": "calvin klain"
},
"locale": "pt-BR"
}
```
- `id`: Brand ID. Every brand in your store has a unique ID that can be found under _Catalog > Brands_ in the VTEX Admin.
- `name`: Brand name.
- `text`: Brand description (meta tag description).
- `siteTitle`: Brand page title (tag title).
- `keywords`: Object containing the translations of **each** similar word for the brand.
- `locale`: Target translation locale.
### Step 8 - Translate Product
To translate a product, follow these steps:
#### Mutation
Complete the main text box with the following mutation command:
```gql
mutation translate($args:ProductInputTranslation, $locale:Locale){
translateProduct(product:$args,locale:$locale)
}
```
#### Query variables
Complete the _Query variables_ section with the desired translations for each parameter.
```json
{
"args":{
"id": "45",
"name": "Câmera Retrô",
"description": "Esta é uma descrição genérica deste produto.",
"shortDescription": "Esta é uma breve descrição genérica deste produto.",
"title": "Câmera Retrô - Store Components",
"metaTagDescription": "Compre os melhores produtos em nossa loja",
"linkId": "black-steel-film-camera",
"keywords": [
"lomografia",
"vintage"]
},
"locale": "pt-BR"
}
```
- `id`: Product ID. Every product in your store has a unique ID, which can be found under _Catalog > Products and SKUs_ in the VTEX Admin.
- `name`: Product name.
- `description`: Product description.
- `shortDescription`: Additional short description.
- `title`: Page title (tag title)
- `metaTagDescription`: Description (meta tag description).
- `keywords`: Object containing the translations of **each** similar word for the product.
- `linkId`: The `textLink` (must **not** be translated unless your store is cross-border).
- `locale`: Target translation locale.
> ℹ️ If you have a cross-border store, the `linkId` serves as the product URL slug. The [Rewriter](https://developers.vtex.com/docs/guides/rewriter) app will automatically create an alias using the translated slug for each target locale and store it in the `resolveAs` field for that locale's internal route. For example, a product with the slug `blue-top-retro-camera` at `http://{storename}.com/us/blue-top-retro-camera/p` could have the translated slug `camera-retro-azul` for the `pt-BR` binding, as in `http://{storename}.com/br/camera-retro-azul/p`.
### Step 9 - Translate SKU
To translate a SKU, follow these steps:
#### Mutation
Complete the main text box with the following mutation command:
```
mutation translate($args:SKUInputTranslation, $locale:Locale){
translateSKU(sku:$args,locale:$locale)
}
```
#### Query variables
Complete the _Query variables_ section with the desired translations for each parameter.
```json
{
"args":{
"id": "46",
"name": "Mixer Retro - Marrom"
},
"locale": "pt-BR"
}
```
- `id`: SKU ID. Every product in your store has a unique ID, which can be found under _Catalog > Products and SKUs_ in the VTEX Admin.
- `name`: SKU name.
- `locale`: Target translation locale.
### Step 10 - Translate SKU or Product Specification
To translate a SKU or product specification, follow these steps:
#### Mutation
Complete the main text box with the following mutation command:
```gql
mutation translate($args:FieldInputTranslation, $locale:Locale){
translateField(field:$args,locale:$locale)
}
```
#### Query variables
Complete the _Query variables_ section with the desired translations for each parameter.
```json
{
"args":{
"fieldId": "31",
"name": "Cor"
},
"locale": "pt-BR"
}
```
- `fieldId`: The ID for a product or SKU specification. Every product or SKU specification in your store has a unique ID, which can be found following the instructions for [SKU specifications](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/6UjLHdAT5YLuflki10SXLr?locale=en) or [product specifications](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/4fcdmJzQ6QYA9zWf3bLWin).
- `name`: Specification name.
- `locale`: Target translation locale.
### Step 11 - Translate Specification Values
To translate specification values, follow these steps:
#### Mutation
Complete the main text box with the following mutation command:
```gql
mutation translate($args:FieldValueInputTranslation, $locale:Locale){
translateFieldValues(fieldValues:$args,locale:$locale)
}
```
#### Query variables
Complete the _Query variables_ section with the desired translations for each parameter.
```json
{
"args": {
"fieldId": "31",
"fieldValuesNames":[
{
"id":"91",
"name":"Azul"
},
{
"id": "92",
"name": "Vermelho"
}
]
},
"locale": "pt-BR"
}
```
- `fieldId`: The ID for a product or SKU specification. Every product or SKU specification in your store has a unique ID, which can be found following the instructions for [SKU specifications](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/6UjLHdAT5YLuflki10SXLr?locale=en) or [product specifications](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/4fcdmJzQ6QYA9zWf3bLWin).
- `fieldValuesNames`: An object containing:
- `id`: Specification value ID.
- `name`: Specification value name.
- `locale`: Target translation locale.
> You can retrieve ID values by running the following query:
>
> ```gql
>query{
> fieldValues(fieldId:"24"){
> fieldValueId
> value
> }
>}
>```
>
> Where `fieldId` is the specification ID, which you can find by following the guide [Products and SKU Specifications](https://help.vtex.com/en/tracks/catalog-101--5AF0XfnjfWeopIFBgs3LIQ/6UjLHdAT5YLuflki10SXLr?locale=en).
### Step 12 - Check Your Changes
After performing the desired mutations, you can check your changes through a query in the GraphQL IDE:
1. In the **GraphQL admin IDE**, after choosing the `vtex.messages` app, write the following query command in the text box that is displayed:
```json
query GetTranslation($args2: TranslateArgs!) {
translate(args: $args2)
}
```
2. Then, to fill in the `Query Variables` box, you must provide the following parameters:
- `from`: source message locale.
- `messages`: a list of the messages you want to check translations, containing the following parameters:
- `content`: source message string.
- `context`: ID of the product/brand/category you want to check the translation. IDs can be found in your store's registration on the admin under Product > Catalog.
- `to`: target translation locale.
Take the following example:
```json
{
"args2": {
"indexedByFrom": [
{
"from": "en-US",
"messages": [
{
"content": "Original product name in English",
"context": "543123"
}
]
}
],
"to": "pt-BR"
}
}
```
3. After adjusting your query, click the play button to run it. The expected response is the translated message in the target locale.
For the given example, the expected response is as follows:
```json
{
"data": {
"translate": [
"Nome do produto em português"
]
}
}
```Was this feedback useful?
|
Grammar review summaryReview for
|
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
Grammar reviewer
📝 [Grammar reviewer] reported by reviewdog 🐶
"ID, which can be found" is slightly more formal and grammatically precise than "ID that can be found." "Catalog" should be capitalized and bolded as it refers to a specific section in the VTEX Admin interface.
📝 [Grammar reviewer] reported by reviewdog 🐶
The JSON example for brand keywords shows a single string, but other examples (category, product) show an array. Assuming consistency is desired and an array is the intended structure for "each similar word," "A list of translated keywords" is a more precise description.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Catalog" should be capitalized and bolded as it refers to a specific section in the VTEX Admin interface.
📝 [Grammar reviewer] reported by reviewdog 🐶
The JSON example shows keywords as an array of strings. "A list of translated keywords" is a more precise description than "Object containing the translations of each similar word."
📝 [Grammar reviewer] reported by reviewdog 🐶
The description refers to an "SKU ID," so it should state "Every SKU" instead of "Every product" for accuracy. "Catalog" should be capitalized and bolded as it refers to a specific section in the VTEX Admin interface.
📝 [Grammar reviewer] reported by reviewdog 🐶
"By following" is the correct prepositional phrase in this context.
📝 [Grammar reviewer] reported by reviewdog 🐶
"By following" is the correct prepositional phrase in this context.
📝 [Grammar reviewer] reported by reviewdog 🐶
The JSON example shows fieldValuesNames as an array of objects, not a single object. "An array of objects" is more precise.
| @@ -1,10 +1,10 @@ | |||
| --- | |||
| title: "Translating Catalog content" | |||
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
In titles, major words (nouns, verbs, adjectives, adverbs, and pronouns) are typically capitalized.
| title: "Translating Catalog content" | |
| title: "Translating Catalog Content" |
| --- | ||
| title: "Translating Catalog content" | ||
| excerpt: "Overwrite automatic message translations from the catalog with more representative content from your store." | ||
| excerpt: "Learn how to overwrite automatic message translations from the catalog." |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Overwrite" is a single word. "Catalog" should be capitalized when referring to the specific system or feature, as implied by the context of "Catalog API" and "Catalog messages."
| excerpt: "Learn how to overwrite automatic message translations from the catalog." | |
| excerpt: "Learn how to overwrite automatic message translations from the Catalog." |
| updatedAt: "2025-10-29T19:24:24.450Z" | ||
| --- | ||
|
|
||
| In this guide, you'll learn how to overwrite an automatic message translation from the catalog, such as a product name or a product description, with more specific and representative content of your store. |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Overwrite" is a single word. "Catalog" should be capitalized when referring to the specific system or feature. Rephrased for conciseness and clarity.
| In this guide, you'll learn how to overwrite an automatic message translation from the catalog, such as a product name or a product description, with more specific and representative content of your store. | |
| In this guide, you'll learn how to overwrite an automatic message translation from the Catalog, such as a product name or a product description, with content more specific and representative of your store. |
| If you have already performed the desired mutations, you can check your changes through a query in the GraphQL IDE: | ||
| 1. In the **GraphQL admin IDE**, after choosing the `vtex.messages` app, write the following query command in the text box that is displayed: |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Admin" should be capitalized when referring to the specific administrative interface or a proper noun in this context.
| 1. In the **GraphQL admin IDE**, after choosing the `vtex.messages` app, write the following query command in the text box that is displayed: | |
| 1. In the **GraphQL Admin IDE**, after choosing the `vtex.messages` app, write the following query command in the text box that is displayed: |
| } | ||
| ``` | ||
| 2. Then, to fill in the `Query Variables` box, you must provide the following parameters: |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Fill in the Query Variables box with the following parameters" is more direct and concise for an instruction.
| 2. Then, to fill in the `Query Variables` box, you must provide the following parameters: | |
| 2. Then, fill in the `Query Variables` box with the following parameters: |
| - `from`: source message locale. | ||
| - `messages`: a list of the messages you want to check translations, containing the following parameters: | ||
| - `content`: source message string. | ||
| - `context`: ID of the product/brand/category you want to check the translation. IDs can be found in your store's registration on the admin under Product > Catalog. |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"In the Admin" is a more appropriate prepositional phrase than "on the admin." "Admin" should be capitalized when referring to the specific administrative interface. "Catalog" should be capitalized and bolded as it refers to a specific section in the VTEX Admin interface.
| - `context`: ID of the product/brand/category you want to check the translation. IDs can be found in your store's registration on the admin under Product > Catalog. | |
| - `context`: ID of the product/brand/category you want to check the translation. IDs can be found in your store's registration in the Admin under **Product > Catalog**. |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Meta-tag" is typically hyphenated when used as a compound adjective modifying "description."
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Meta-tag" is typically hyphenated when used as a compound adjective modifying "description."
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Meta-tag" is typically hyphenated when used as a compound adjective modifying "description."
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"SKU" is an acronym and should be capitalized. "Product Specification" is a specific type of setting and should be capitalized for consistency with other listed items like "Category" and "Brand."
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Overwrite" is a single word. Rephrased for conciseness and clarity.
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"The VTEX Admin" is a more common and natural phrasing when referring to the administrative interface.
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Guidance" is a more appropriate word choice than "orientations" in this context, meaning advice or information that helps someone to solve a problem or make a decision.
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
Rephrased for conciseness and better flow. "Automatic translation for a product name" is clearer.
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
"Catalog" should be capitalized and bolded as it refers to a specific section in the VTEX Admin interface.
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
The JSON example shows keywords as an array of strings. "A list of translated keywords" is a more precise description than "Object containing the translations of each similar word."
Types of changes
EDU-10819