This feature is in beta, which means that we are working to improve it. If you have any questions or feedback, please contact our Support.

Learn how to create translations and integrate localized content for catalog entities with the multi-language feature.

The multi-language feature enables the following capabilities:

• Granular content management: Retrieve and store translations for products, SKUs, categories, brands, specifications, collections, and services.
• Integrated translation workflows: It enables automated translations with a Translation Management System (TMS).
• Multiple storefront technologies: Consume translations across Store Framework and headless implementations.
• Localized experience: Provide customers with localized shopping experiences across multiple markets.

To see the complete documentation of the multi-language endpoints, check the Catalog API.

The multi-language feature supports various integration scenarios:

Use case	Description
Multilingual storefront	Displays translated product names, descriptions, and specifications based on the customer's locale as identified by the storefront.
TMS integration	Connects your Translation Management System (TMS) to automatically push and pull translations via the Catalog API.
Business expansion	Seamlessly adapts your catalog for new geographic markets without duplicating products.
SEO optimization	Provides localized meta descriptions, keywords, and URL slugs for better search engine rankings in each market.
Headless commerce	Fetches translated catalog data for headless storefront applications.

When you send translated content using the multi-language feature, the workflow is as follows:

The merchant or an integrated TMS makes a request to create or update the translation of a catalog entity, such as product or category. The Catalog system validates and stores the translated fields per locale, then triggers an update event to Intelligent Search.

Intelligent Search indexes or reindexes the translated entity content to make it searchable and filterable in the storefront by the selected locale. This process runs asynchronously and usually completes within a few minutes. Larger amounts of data may take longer.

The storefront components (in this case, Store Framework and Checkout) query Intelligent Search and the Catalog system at render time, so it automatically retrieves and displays the translations according to the customer's selected locale. No manual configuration or synchronization is needed.

The available storefront solutions for the multi-language feature are Store Framework and headless implementations.

There are two main approaches to consuming translated catalog data, depending on your storefront implementation.

For most storefront implementations, Intelligent Search is the recommended approach for consuming translated content. When using Intelligent Search:

• Translations are automatically indexed after being saved using the multi-language endpoints.
• Search results, filters, and facets display translated content based on the customer's locale.
• No additional API calls are required, since the storefront receives translated data automatically.
• Performance is optimized for navigation via native cache strategies.

When to use Intelligent Search:

Implementation	Intelligent Search usage
Store Framework	✅ Yes (default behavior)
Headless with IS	✅ Yes
CMS Portal (Legacy)	⚠️ May require additional configuration
FastStore	❌ Not available

When to use the direct Catalog API:

• You need specific entity translations not available in search results.
• You're building VTEX Admin tools or back-office integrations.
• You need to fetch translations for validation or synchronization.

See below the implementation by storefront type for consuming localized content:

• Store Framework
• Headless

The multi-language feature is not available for FastStore.

To enable the multi-language feature for Store Framework in your store, submit a request via Support.

For stores built with Store Framework, localized content is consumed automatically:

1. Locale detection: The store detects the consumer's locale from the URL binding (e.g., store.com/es-ES/) or browser settings.
2. Automatic translation: Intelligent Search returns translated content for the detected locale.
3. Component rendering: Store Framework components (product shelf, product details, search results) display the translated content without additional configuration.

No code changes are required: Once you submit translations via the multi-language feature, they appear automatically in your Store Framework storefront.

For headless storefronts, you either use the Intelligent Search API or the Catalog API directly, depending on your needs.

Option A: Using Intelligent Search API

Query Intelligent Search with the desired locale to receive translated results:

Option B: Use Catalog API directly

Query the Catalog API with the Accept-Language header:

Open a support ticket requesting the activation of the Catalog multi-language feature for your account. Once the VTEX team activates it, they will contact you to inform you that you can start using the feature.

The simultaneous use of both the multi-language APIs and Messages APIs (GraphQL) is not supported for catalog entities. Therefore, once the new feature is activated, you will no longer be able to manage translations using GraphQL.

To successfully use the multi-language feature, the user or API key must have the License Manager resources below; otherwise, they will receive a 403 Forbidden error message:

Product	Category	Resource
Catalog	Content	Categories Management

When a translation is not available for a requested locale:

• Intelligent Search: Returns content in the store's default language.
• Catalog API: Returns only entities that have translations in the requested locale.

Consider implementing fallback logic in headless implementations to handle missing translations gracefully.

The solution is composed of a combination of two methods:

• PUT: Creates or updates translations for catalog entities.
• GET: Retrieves translations previously created using the PUT method. By default, it returns all existing translations for the entity, but you can filter results for a specific language using the locale query parameter.

They are supported for the following catalog entities:

• Products
• SKUs
• Specifications
• Categories
• Brands
• Attachments
• Collections
• Services

All locale codes follow the IETF BCP 47, for example:

Locale	Description
en-US	English (United States)
es-ES	Spanish (Spain)
pt-BR	Portuguese (Brazil)
fr-FR	French (France)
de-DE	German (Germany)

See below an example of how the multi-language feature works for a product:

Method: PUT

Endpoint: https://{accountName}.{environment}.com.br/api/catalog/pvt/product/{productId}/language

Request body example:

Responses:

• 201 Created: The translation was created or updated successfully.
• 400 Bad Request: The request body is invalid.
• 403 Forbidden: The user or API key does not have the required permissions.
• 404 Not Found: The product ID does not exist.
• 409 Conflict: The translation already exists with the same fields.

For information about how to handle errors, see the Troubleshooting section.

After creating translations for an entity, you can use the GET endpoint to retrieve them. See below an example of how to retrieve translations for a product.

Method: GET

Endpoint: https://{accountName}.{environment}.com.br/api/catalog/pvt/product/{productId}/language

Query parameters: locale=en-US (Optional)

If you wish to retrieve translations for a specific language, use the query parameter locale, as described in the Locale format section. Otherwise, you will receive all translations for the entity.

Response body example: 200 OK

See below the most common issues and their respective solutions for the multi-language feature:

Issue	Solution
Translations not appearing on storefront	Wait a few minutes for Intelligent Search to reindex. Check that the locale matches your store binding configuration.
403 Forbidden error	Verify that your user or application key has the Categories Management resource enabled.
404 Not Found error	Confirm that the entity ID (product, SKU, category, etc.) exists in the Catalog.
409 Conflict error	The translation may already exist. Use GET to retrieve current translations before updating.

If the issue persists, contact our Support.