VTEX multilingual ecommerce translation now has a newer catalog pathway: the Catalog Multi-Language API announced on October 27, 2026. It enables language-specific content for products, SKUs, categories, specifications and other catalog entities, with different availability stages for headless stores, Store Framework and FastStore. A professional VTEX localization project must coordinate catalog translations, bindings, Intelligent Search, CMS messages, trade policies, checkout and localized URLs rather than treating translated product titles as a finished international store.
This VTEX translation guide covers the new Catalog Multi-Language API, Store Framework multilingual setup, FastStore v4 Localization, VTEX binding configuration, BCP 47 locale codes, Intelligent Search translation indexing, headless API requests, international SEO and order quality assurance. It is written for worldwide merchants, developers, translators and localization managers who need current, careful guidance for cross-border storefront content without confusing the chosen language with currency or sales-channel eligibility.
In brief, identify the deployed storefront and its feature availability; confirm account activation; configure appropriate bindings and locale paths; choose the current supported catalog translation route; supply and verify translated entity fields; test Intelligent Search and documented fallback; localize CMS and interface messages separately; and inspect the complete cart-to-order journey. Preserve SKU identity, physical specifications, price, shipping restrictions and customer rights throughout. The October 27, 2026 release note is a dated checkpoint, not a guarantee that every account has every feature enabled.
Quick answer: the correct translation path depends on your VTEX storefront
For the new Catalog Multi-Language API, start by verifying availability and activation with VTEX and identify whether you use headless, Store Framework or FastStore. The platform documents translating catalog entities through its new endpoints and making those results available to Intelligent Search and supported storefronts. Separately configure bindings and locale context, interface messages, CMS content and trade policies. Older GraphQL catalog translation guidance cannot simply operate alongside the new catalog approach for the same entities.
Important dated release information
VTEX’s October 27, 2026 release note describes general availability of the new Catalog Multi-Language API for headless storefronts, open beta for Store Framework and closed beta for FastStore. The integration guide directs merchants to contact VTEX Support for account activation. Feature stages can change, so teams should check their actual account and the latest official documentation before planning an implementation. This distinction matters when an online tutorial displays a menu that an individual merchant cannot currently access.
Core definitions: language, binding, catalog and sales channel
A locale identifies language and relevant regional formatting conventions. A binding connects storefront context such as canonical address and locale to currency and sales channels. A catalog translation expresses the same entity in another language. A trade policy or sales channel determines commercial eligibility and may influence assortment, pricing and logistics. Intelligent Search delivers indexed discovery results. These concepts must be coordinated, but they should not be used as synonyms.
Thirty practical lessons for VTEX translation and localization
1. Start with the October 2026 VTEX multi-language release
VTEX announced its new Catalog Multi-Language API on October 27, 2026, offering catalog translation management across products, SKUs and related entities. Its rollout status differs by storefront technology. The most important habit is to separate the text seen by the buyer from the configuration that makes an offer true. A fluent sentence cannot correct an unavailable SKU, unsuitable trade policy or incorrect price. Each needs its proper owner.
Example. A team copies a legacy GraphQL translation tutorial into a store using the newer feature and assumes both systems can write the same catalog fields. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Confirm the account’s feature activation and implementation type, then consult the current multi-language integration guide before touching catalog translations. Start with one controlled entity and record the account, binding, locale code, translated field, stored source value and expected storefront result. This narrows complex issues to evidence that can be repeated.
What counts as proof. Record the enabled feature, storefront technology and actual API response for a representative product. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
2. Know the activation and availability boundaries
The October 27 release describes general availability for headless storefronts, open beta for Store Framework and closed beta for FastStore, with support involvement in activation. One multilingual experience crosses several services. The binding chooses context, catalog stores content, search exposes items, CMS supplies editorial material and checkout computes commercial outcomes. A translation can be right in one and wrong in another.
Example. A manager promises FastStore localization to a launch team before confirming that the store has access to the closed-beta capability. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Ask VTEX Support about eligibility, prerequisites and actual account activation; do not treat documented capability as proof that every account has access. Have a fluent reviewer assess the customer meaning and a commerce specialist check technical facts. The two perspectives should agree on the product, restriction or action being described.
What counts as proof. Validate the feature in the account rather than relying on generic marketing language. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
3. Differentiate Store Framework and FastStore
VTEX Store Framework and FastStore have different approaches to message resources, CMS content and locale configuration. Instructions for one are not automatically valid for the other. A good translation is clear enough for a person to act on and accurate enough to reconcile with a system record. For global ecommerce, this means preserving identifiers, numerical facts, exclusions and the real next step.
Example. A developer expects the Store Framework /messages directory to control a FastStore CMS page and cannot find the expected text. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Identify the deployed storefront stack and restrict implementation guidance to its supported translation and localization path. Test from a fresh browser session and a direct localized URL, not only after clicking through an editor’s preview. This reveals language state and route failures that warm sessions can disguise.
What counts as proof. Check the page-rendering application, CMS and catalog retrieval method in staging. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
4. Language localization versus cross-border commerce
Translating text and formatting locale-sensitive content does not itself change prices, tax, fulfillment or product availability. VTEX trade policies govern important commercial conditions. Do not confuse feature availability with feature activation. The platform documentation describes capabilities and their release stages, but an actual account, storefront version and support arrangement determine which route can be used.
Example. A Spanish site promises an item is shippable in a country where the assigned sales channel does not actually offer it. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Design separate language and market matrices; review which bindings and sales channels serve the intended country and item. Run a normal flow and an intentional missing-data or invalid-input flow. The second check reveals fallback and error handling that polished content reviews often overlook.
What counts as proof. Compare the catalog text, assortment, checkout shipping response and final currency under the chosen binding. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
5. Understand a VTEX binding
A binding associates storefront context including canonical domain, locale, currency and sales channels; its exact setup depends on the storefront architecture. Think about readers who do not start on a homepage. A direct product link, search result, order email or account history can be their first contact. The language and market context should make sense in each entry path.
Example. A customer changes language while the session retains a mismatched sales context, producing inconsistent navigation and cart totals. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Map domains, locale paths, bindings and their trade-policy association before translating URLs or designing the language switcher. Keep text and underlying identity separate: a translated name can vary, but product, SKU, order and service identifiers must still refer to the intended resource.
What counts as proof. Open each localized domain or path directly and inspect the active binding and available catalog. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
6. Avoid mixed root and locale-path patterns
VTEX documentation warns about inconsistent path scopes when one language occupies the root and another uses a prefix on the same host. Missing content, stale indexes and old translation jobs can masquerade as linguistic mistakes. Before rewriting a sentence, trace what created the displayed value and whether a newer value has reached the active storefront.
Example. An English root URL and a Portuguese /pt route create different segment cookie scopes, causing unexpected language and session behavior. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Use a coherent locale-path strategy for all languages on one shared host or separate intended language domains as appropriate. If a result is wrong, distinguish stored catalog translation, search indexing, CMS publication, frontend rendering and commerce policy before changing values. Repairing the wrong layer wastes time and introduces new defects.
What counts as proof. Test direct entry, navigation, cart retention and browser refresh for every locale route in a clean session. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
7. Catalog Multi-Language API as the modern translation route
The Catalog Multi-Language API manages translated entities and can integrate with translation management systems, rather than requiring separate products for each language. Local language can require natural phrasing and regional presentation, yet this is not permission to rewrite material specifications, warranty restrictions, delivery conditions or financial calculations.
Example. A merchant duplicates the entire catalog for a second language, creating inconsistent IDs and fragmented inventory reporting. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Keep product identity stable and store supported translated fields by locale through the documented API and account permissions. Treat release notes as dated evidence. Check which feature version and availability stage apply rather than assuming all older tutorials or later interface screenshots describe the same account.
What counts as proof. Retrieve the same product ID in two locales and compare translated fields without changing the SKU or commercial record. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
8. Do not mix the new API with legacy GraphQL catalog writes
VTEX explicitly states that Catalog Multi-Language API and the older GraphQL-based catalog translation approach cannot be used simultaneously for catalog entities once the new feature is activated. An international customer needs meaningful failure messages as well as elegant marketing copy. A rejected address, unavailable variant or payment problem should have a translated explanation that matches what the service actually returned.
Example. An integration tries to update legacy Messages or catalog-graphql overrides after enabling the new API and reports that localized copy will not persist. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Plan a deliberate transition and turn off obsolete catalog translation writes while preserving separate storefront message handling where supported. Document the observed behavior and the person responsible for corrections. A completed test is useful only if a future reviewer can repeat it after the next platform or catalog release.
What counts as proof. Verify a new translation using the supported GET endpoint and confirm that no old job overwrites it. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
9. Product names and descriptions
Product translation covers titles, descriptions, short descriptions and other documented fields; copy still needs technical and commercial review. The most important habit is to separate the text seen by the buyer from the configuration that makes an offer true. A fluent sentence cannot correct an unavailable SKU, unsuitable trade policy or incorrect price. Each needs its proper owner.
Example. An automated translation changes the fabric composition of a shirt and makes it sound like a different material from the actual SKU. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Translate the approved attributes and descriptions, protect measurements and claims, and have a product specialist review exceptions. Start with one controlled entity and record the account, binding, locale code, translated field, stored source value and expected storefront result. This narrows complex issues to evidence that can be repeated.
What counts as proof. Read back both locales and verify the original product and material facts remain unchanged. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
10. SKU names and variant display
SKU translation supports visible option naming, but SKU IDs, size relations, stock and fulfillment should stay anchored to actual goods. One multilingual experience crosses several services. The binding chooses context, catalog stores content, search exposes items, CMS supplies editorial material and checkout computes commercial outcomes. A translation can be right in one and wrong in another.
Example. A translated color or size label points to a different SKU in a product selector because display text was treated as a stable key. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Keep SKU references separate from translated names and test product selectors, line items and order records across languages. Have a fluent reviewer assess the customer meaning and a commerce specialist check technical facts. The two perspectives should agree on the product, restriction or action being described.
What counts as proof. Select the same SKU in two languages and compare cart identifiers, inventory status and item quantities. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
11. Categories, brands and navigation
Catalog translation can include category and brand information, while navigation structure determines which items customers discover. A good translation is clear enough for a person to act on and accurate enough to reconcile with a system record. For global ecommerce, this means preserving identifiers, numerical facts, exclusions and the real next step.
Example. A localized category is named correctly but its menu directs visitors into an unrelated collection, because only the visible label was reviewed. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Map each translated category and brand to its actual entity and test breadcrumbs, menus and category links end to end. Test from a fresh browser session and a direct localized URL, not only after clicking through an editor’s preview. This reveals language state and route failures that warm sessions can disguise.
What counts as proof. Browse into an item from a translated menu without pasting its deep URL and confirm the same item identity. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
12. Specifications and localized facets
Product and SKU specifications have names and values that can be language-sensitive, but structured physical meaning must not change. Do not confuse feature availability with feature activation. The platform documentation describes capabilities and their release stages, but an actual account, storefront version and support arrangement determine which route can be used.
Example. A Spanish dimension filter is translated as a mass filter, and a shopper chooses an unsuitable product based on the result. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Review specification IDs, units, possible values and the facet representation returned by Intelligent Search. Run a normal flow and an intentional missing-data or invalid-input flow. The second check reveals fallback and error handling that polished content reviews often overlook.
What counts as proof. Filter equivalent products in two locales and confirm identical stable specification choices and product IDs. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
13. Attachments, services and collections
The new feature documents translations for attachments, collections, services and other catalog entities beyond basic product descriptions. Think about readers who do not start on a homepage. A direct product link, search result, order email or account history can be their first contact. The language and market context should make sense in each entry path.
Example. A service add-on carries untranslated restrictions even though the main product title and category are correct. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Include ancillary services, collection labels and attachment instructions in the inventory, prioritizing those affecting price or eligibility. Keep text and underlying identity separate: a translated name can vary, but product, SKU, order and service identifiers must still refer to the intended resource.
What counts as proof. Test one product with an add-on service and confirm the same service terms in each supported language. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
14. Locale identifiers follow BCP 47
The multi-language guide uses IETF BCP 47-style locale codes such as en-US, es-ES and pt-BR; inconsistent codes can cause requests to miss their intended translations. Missing content, stale indexes and old translation jobs can masquerade as linguistic mistakes. Before rewriting a sentence, trace what created the displayed value and whether a newer value has reached the active storefront.
Example. An integration saves a product for a language value that does not match the locale requested by the storefront binding. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Maintain a documented locale mapping among the TMS, catalog API, CMS and frontend, and validate exact code strings. If a result is wrong, distinguish stored catalog translation, search indexing, CMS publication, frontend rendering and commerce policy before changing values. Repairing the wrong layer wastes time and introduces new defects.
What counts as proof. Request a known translated entity in the intended locale and verify the exact returned content. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
15. PUT updates and GET verification
VTEX documents creating or updating catalog translations through PUT endpoints and retrieving them through GET, with supported entity paths and locale filters. Local language can require natural phrasing and regional presentation, yet this is not permission to rewrite material specifications, warranty restrictions, delivery conditions or financial calculations.
Example. A provider reports success after sending a translation batch but never reads back values, so a field rejected by validation goes unnoticed. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Check request body fields, response status and entity ID, then use the documented read endpoint to compare the stored translation with the approved source. Treat release notes as dated evidence. Check which feature version and availability stage apply rather than assuming all older tutorials or later interface screenshots describe the same account.
What counts as proof. Run a controlled product translation and inspect the GET result rather than trusting only an import log. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
16. API permissions and error responses
The platform documents permission requirements and meaningful response codes such as 400, 403, 404 and 409 for relevant catalog translation operations. An international customer needs meaningful failure messages as well as elegant marketing copy. A rejected address, unavailable variant or payment problem should have a translated explanation that matches what the service actually returned.
Example. A translation tool retries a 403 authorization error as though it were an intermittent network problem, filling logs without changing anything. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Diagnose missing permissions separately from invalid payloads, absent entities and conflicts; do not expose API credentials to the storefront. Document the observed behavior and the person responsible for corrections. A completed test is useful only if a future reviewer can repeat it after the next platform or catalog release.
What counts as proof. Prove that an authorized integration can update a harmless test entry and that an unauthorized client cannot. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
17. Intelligent Search indexing is asynchronous
After catalog translations are saved, VTEX Intelligent Search indexing or reindexing can take time before the localized content is discoverable. The most important habit is to separate the text seen by the buyer from the configuration that makes an offer true. A fluent sentence cannot correct an unavailable SKU, unsuitable trade policy or incorrect price. Each needs its proper owner.
Example. An editor sees the new French title through the API but an old French search result remains until indexing catches up. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Compare stored translation with indexed search output, allow for the documented asynchronous process and inspect any persistent indexing failure. Start with one controlled entity and record the account, binding, locale code, translated field, stored source value and expected storefront result. This narrows complex issues to evidence that can be repeated.
What counts as proof. Query the actual localized storefront search until the expected item and facet values become visible. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
18. Headless Intelligent Search locale requests
A headless implementation can request localized search results using locale context, but the client must pass the same intended locale through its search flow. One multilingual experience crosses several services. The binding chooses context, catalog stores content, search exposes items, CMS supplies editorial material and checkout computes commercial outcomes. A translation can be right in one and wrong in another.
Example. A Portuguese product detail page is correct, while the results grid uses default English because its search request omits the locale. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Trace the requested locale into the Intelligent Search API and ensure product listings, facets and detail pages use a consistent binding. Have a fluent reviewer assess the customer meaning and a commerce specialist check technical facts. The two perspectives should agree on the product, restriction or action being described.
What counts as proof. Compare the network request and rendered results for two target locales. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
19. Direct Catalog API retrieval and Accept-Language
The catalog integration guide describes direct retrieval scenarios where language-sensitive results are requested via an Accept-Language header. A good translation is clear enough for a person to act on and accurate enough to reconcile with a system record. For global ecommerce, this means preserving identifiers, numerical facts, exclusions and the real next step.
Example. An administration widget queries SKU details without the intended language header and treats the default value as a failed translation. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Use the documented endpoint and explicit header when appropriate, distinguishing private API access from public storefront requests. Test from a fresh browser session and a direct localized URL, not only after clicking through an editor’s preview. This reveals language state and route failures that warm sessions can disguise.
What counts as proof. Inspect the returned entity, the exact requested locale and the account’s permissions for that endpoint. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
20. Missing translations behave differently across APIs
The VTEX guide describes default-language fallback from Intelligent Search, while direct Catalog API retrieval can return only entities with translations in the requested locale. Do not confuse feature availability with feature activation. The platform documentation describes capabilities and their release stages, but an actual account, storefront version and support arrangement determine which route can be used.
Example. A developer assumes a missing localized product should appear identically through every API and hides a real coverage gap. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Design an explicit missing-data policy for each retrieval path and decide whether to fall back, inform the reader or withhold a risky offer. Run a normal flow and an intentional missing-data or invalid-input flow. The second check reveals fallback and error handling that polished content reviews often overlook.
What counts as proof. Remove a harmless test translation and compare the two retrieval behaviors, confirming the storefront response remains safe. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
21. Store Framework frontend messages
Store Framework app interface messages can live in a /messages directory, separately from catalog entity translations and commercial data. Think about readers who do not start on a homepage. A direct product link, search result, order email or account history can be their first contact. The language and market context should make sense in each entry path.
Example. A product name is translated by the catalog service while the add-to-cart button and address error remain English. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Locate the message keys for each component, preserve placeholders and translate functional UI flows independently of catalog titles. Keep text and underlying identity separate: a translated name can vary, but product, SKU, order and service identifiers must still refer to the intended resource.
What counts as proof. Test successful and failed cart or checkout actions and inspect the actual rendered messages. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
22. Locale switcher and session continuity
A switcher needs to preserve the correct URL context and make deliberate decisions about whether the current cart and market remain valid. Missing content, stale indexes and old translation jobs can masquerade as linguistic mistakes. Before rewriting a sentence, trace what created the displayed value and whether a newer value has reached the active storefront.
Example. A shopper switches from English to Spanish and the cart unexpectedly changes availability or total without an explanation. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Reconcile the new binding, trade policy and current session, then explain market-driven changes clearly while preserving item identity where possible. If a result is wrong, distinguish stored catalog translation, search indexing, CMS publication, frontend rendering and commerce policy before changing values. Repairing the wrong layer wastes time and introduces new defects.
What counts as proof. Compare cart lines, currency, eligible promotions and delivery conditions before and after switching locale. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
23. FastStore v4 Localization feature limitations
Current VTEX guidance describes FastStore v4 Localization as closed beta with specific CMS and configuration requirements; older FastStore or legacy CMS setups require separate evaluation. Local language can require natural phrasing and regional presentation, yet this is not permission to rewrite material specifications, warranty restrictions, delivery conditions or financial calculations.
Example. A team follows a FastStore localization tutorial against an unsupported version and assumes a missing CMS control is a translation bug. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Check version, support activation, WebOps secrets, localization feature flag and relevant CMS capabilities before assigning translation tasks. Treat release notes as dated evidence. Check which feature version and availability stage apply rather than assuming all older tutorials or later interface screenshots describe the same account.
What counts as proof. Verify the supported locale appears in the actual CMS and rendered preview for an eligible test store. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
24. CMS content per locale
Translated catalog data is not the same as editorial CMS material such as homepages, hero banners, landing pages and calls to action. An international customer needs meaningful failure messages as well as elegant marketing copy. A rejected address, unavailable variant or payment problem should have a translated explanation that matches what the service actually returned.
Example. The French product card is correct but a homepage banner advertises an English-only promotion and links to another market. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Inventory CMS pages by locale, translate interface and editorial content with the right publication workflow, and validate destination URLs and legal claims. Document the observed behavior and the person responsible for corrections. A completed test is useful only if a future reviewer can repeat it after the next platform or catalog release.
What counts as proof. Review the homepage-to-product route in each language, including mobile banners and linked policy pages. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
25. Localized product URLs and search metadata
VTEX supports internationalized URL approaches tied to bindings and catalog translation capabilities; slugs, meta content and alternate signals require careful planning. The most important habit is to separate the text seen by the buyer from the configuration that makes an offer true. A fluent sentence cannot correct an unavailable SKU, unsuitable trade policy or incorrect price. Each needs its proper owner.
Example. The Spanish product has a translated description, but the URL sends the reader to the English storefront and canonical metadata refers elsewhere. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Keep product identity stable beneath localized routes and review slugs, redirects, canonicals and hreflang with the deployed storefront technology. Start with one controlled entity and record the account, binding, locale code, translated field, stored source value and expected storefront result. This narrows complex issues to evidence that can be repeated.
What counts as proof. Open both language URLs directly and confirm they resolve to equivalent available products and readable metadata. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
26. Catalog URL aliases under legacy approaches
Older cross-border localization guidance describes binding-specific aliases through GraphQL and Rewriter, but its applicability must be checked against the new API setup. One multilingual experience crosses several services. The binding chooses context, catalog stores content, search exposes items, CMS supplies editorial material and checkout computes commercial outcomes. A translation can be right in one and wrong in another.
Example. A developer copies the legacy alias-mutation approach into an account already using the newer catalog translation service. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Choose the correct URL and catalog workflow for the current release, then check route resolution rather than assuming historical examples still apply. Have a fluent reviewer assess the customer meaning and a commerce specialist check technical facts. The two perspectives should agree on the product, restriction or action being described.
What counts as proof. Verify that translated slug access works without generating conflicting aliases or redirect loops. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
27. Regional price and assortment rules
Trade policies and sales channels govern actual prices, promotions and inventory eligibility; a translated item appears only when commerce conditions permit it. A good translation is clear enough for a person to act on and accurate enough to reconcile with a system record. For global ecommerce, this means preserving identifiers, numerical facts, exclusions and the real next step.
Example. A multi-country launch makes a product’s French text available but wrongly advertises delivery to a restricted country. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Review the catalog assortment, prices and logistics tied to the active sales channel before publishing the localized product route. Test from a fresh browser session and a direct localized URL, not only after clicking through an editor’s preview. This reveals language state and route failures that warm sessions can disguise.
What counts as proof. Test an eligible and an ineligible destination and compare the storefront claims with checkout calculation. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
28. Order placement and transactional email boundaries
VTEX documentation states some order-placed and transactional product information is translated, while My Account product information may need customization. Do not confuse feature availability with feature activation. The platform documentation describes capabilities and their release stages, but an actual account, storefront version and support arrangement determine which route can be used.
Example. An order confirmation is localized but the customer’s account page still shows default-language item names, creating confusion about the order. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Audit cart, order placed, notification and My Account as separate surfaces; preserve order item IDs and real monetary data. Run a normal flow and an intentional missing-data or invalid-input flow. The second check reveals fallback and error handling that polished content reviews often overlook.
What counts as proof. Place an authorized test order and compare the confirmation with the account view and recorded purchase. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
29. SEO localization without search cannibalization
Each language version should answer the real audience’s query rather than duplicate generic text with only a changed locale marker. Think about readers who do not start on a homepage. A direct product link, search result, order email or account history can be their first contact. The language and market context should make sense in each entry path.
Example. A site publishes four almost identical product pages across languages but gives search engines ambiguous canonicals and no useful alternate relationships. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Write genuine audience-facing metadata and visible descriptions, define equivalents and test that language-specific routes remain indexable as intended. Keep text and underlying identity separate: a translated name can vary, but product, SKU, order and service identifiers must still refer to the intended resource.
What counts as proof. Inspect rendered canonical and alternate tags alongside the actual localized product and its market availability. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
30. A phased multilingual rollout
A robust rollout begins with one representative product journey and clear ownership of API, CMS, search, checkout and after-sales translation. Missing content, stale indexes and old translation jobs can masquerade as linguistic mistakes. Before rewriting a sentence, trace what created the displayed value and whether a newer value has reached the active storefront.
Example. A large catalog translation is pushed live before the team checks missing translations, indexing delays or a failed address state. The customer experiences a single page or checkout journey, even though several VTEX services may contribute to its text and behavior. Determine which service supplied the value before asking someone to rewrite it.
How to implement or repair it. Launch one supported locale after complete testing, monitor customer reports and widen product coverage with documented regression cases. If a result is wrong, distinguish stored catalog translation, search indexing, CMS publication, frontend rendering and commerce policy before changing values. Repairing the wrong layer wastes time and introduces new defects.
What counts as proof. Record the feature version, binding, locale, product and observed outcome so an update can be tested again. The acceptance result should describe exactly what the customer saw and what the platform allowed, with no invented promise or missing restriction. Keep that example as a future regression test.
Twelve practical situations for a multilingual VTEX store
Situation 1: A French title is saved but search still shows English
Read the new catalog translation using its supported retrieval method, then inspect indexing state and the locale used by Intelligent Search. A stored update may not appear instantly in an asynchronous search index. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 2: A merchant wants FastStore localization immediately
Check FastStore v4, CMS prerequisites and support activation, then verify whether the account has access to the capability described as closed beta in the October 27 announcement. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 3: Old GraphQL translation jobs stop working
Determine whether the new Multi-Language API has been activated. Avoid simultaneous catalog writes through a legacy path that the newer setup explicitly does not support. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 4: A language switch sends customers to the wrong market
Trace binding, canonical path, trade policy and session state. Distinguish the desire to change language from an actual request to change shipping eligibility, currency or available products. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 5: A direct localized URL loses its language
Inspect the canonical binding path, route rules, cookies and redirects. Test consistent path prefixes rather than assuming an English root route and a localized subpath behave identically. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 6: A product name is translated but its size chart is not
Inventory SKU specifications, measurement units, charts and any image text. Translate explanations while preserving the real dimensions and approved conversion policies. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 7: A headless request returns default-language values
Inspect its locale parameter or Accept-Language header as appropriate to the endpoint, the exact language identifier and whether the entity has an approved translation. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 8: The catalog API and Intelligent Search disagree about missing content
Verify their documented difference in fallback behavior, then define what the frontend should display without hiding a missing restriction or safety message. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 9: Localized checkout prices do not match the banner
Check the active sales channel’s trade policy, promotions, currency and cart totals. The translation of a banner is not authority to change a discount. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 10: A translation import fails with authorization errors
Check License Manager roles and API permissions and differentiate a 403 from payload, entity or conflict errors. Credentials should be managed securely, not placed in customer-facing JavaScript. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 11: An order email is translated but account history is English
Inspect order-placed and notification behavior separately from My Account, whose product information can require further customization under the documented setup. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Situation 12: A new locale causes navigation and accessibility failures
Check CMS content, storefront messages, mobile layout, keyboard focus, screen-reader labels and meaningful destination URLs rather than counting translated catalog fields. Capture the binding, locale, actual response and customer-facing result. If the problem involves a factual condition such as price or delivery, involve the owner of that condition before approving translated wording.
Complete the diagnosis by reproducing an ordinary route and a difficult route, such as a missing translation, unavailable SKU or failed form. The repair should keep the same product or order identity and make the customer’s next action understandable in both languages.
Worked example: one running shoe sold in English and Spanish
Imagine a running-shoe merchant with an English storefront and a Spanish-language storefront, sharing much of the catalog but not assuming the same distribution rights everywhere. First identify the intended binding for each language, its canonical address, active sales channels and trade-policy conditions. Choose one shoe with two size variants and a controlled set of specifications. Confirm the store’s eligibility for the new Catalog Multi-Language API, and use the supported workflow to provide approved Spanish names, short and long descriptions, category labels, variant names and relevant specification text. Keep product and SKU identifiers stable; preserve size, materials and warranty facts exactly.
Read translations through the supported catalog API and compare the exact values with the source. Search for the Spanish product through the storefront’s real Intelligent Search flow. If search has not updated, distinguish asynchronous indexing from a failed catalog save. Navigate using the Spanish category and product URL, inspect the site’s routing and localized metadata, and confirm that the correct shoe remains available in the intended sales channel. A translated product must not appear purchasable where the trade policy excludes it. Review the UI messages and promotional CMS blocks separately from the catalog.
Select one size and add it to the cart, then test the language selector. Inspect the line item, currency, applicable promotion, shipping destination and final amount. Use a permitted invalid-address test to verify a clear Spanish rejection. Complete an authorized order and inspect its confirmation email, order-placed page and account history; recognize that those surfaces may have different language behavior. Finally test mobile layout, keyboard access, the direct localized URL after refresh and one missing translation. The store is ready when the shopper can understand every essential step and the commerce records accurately match the product purchased.
Four-week learning and release plan
Week one: document the storefront and its eligibility
Identify Store Framework, headless or FastStore, record feature availability and activation, map bindings, locale codes, sales channels, trade policies and source catalog entities. Choose a small representative assortment and set commercial acceptance tests.
For each milestone, retain a test with the exact account context, locale, product ID, expected translated statement and observed customer outcome. A failed test should name the responsible layer and a concrete correction, not merely report that the site is ‘not localized’.
Week two: enter and validate catalog translations
Create approved content using the supported API, verify GET responses, review identifiers, SKU values and specifications, and observe Intelligent Search indexing. Retire incompatible legacy catalog translation jobs when enabling the new model.
For each milestone, retain a test with the exact account context, locale, product ID, expected translated statement and observed customer outcome. A failed test should name the responsible layer and a concrete correction, not merely report that the site is ‘not localized’.
Week three: connect the customer experience
Configure and review CMS and functional messages, locale switchers, consistent URL paths and search requests. Test cart, checkout, missing translation fallback, rejected delivery addresses and notifications under the right binding.
For each milestone, retain a test with the exact account context, locale, product ID, expected translated statement and observed customer outcome. A failed test should name the responsible layer and a concrete correction, not merely report that the site is ‘not localized’.
Week four: launch carefully and establish maintenance
Inspect mobile layout, accessibility, canonical and alternate metadata, product availability, actual emails and account history. Document owner responsibilities, regression tests and customer feedback, then widen the supported catalog only after tested success.
For each milestone, retain a test with the exact account context, locale, product ID, expected translated statement and observed customer outcome. A failed test should name the responsible layer and a concrete correction, not merely report that the site is ‘not localized’.
Frequently asked questions
What changed for VTEX catalog translation on October 27, 2026?
VTEX announced the newer Catalog Multi-Language API. The dated release describes general availability for headless stores, open beta for Store Framework and closed beta for FastStore, with support activation.
Can the new API and old GraphQL catalog translation run together?
The official guide says they cannot be used simultaneously for catalog entities after activating the new feature. Plan the migration and avoid competing writers.
Does translating a product automatically make it available in another country?
No. Availability, pricing and logistics depend on sales channels and trade policies, not translation alone.
Why is a saved translation not visible in search?
Intelligent Search indexing is asynchronous. Compare stored catalog data, the actual locale request and indexed results, and investigate persistent failure after appropriate indexing.
What happens when a translation is missing?
The documented behavior differs by retrieval method: Intelligent Search can use the store default language, whereas direct Catalog API retrieval can return only entities translated for the requested locale.
How do binding paths affect language switching?
Bindings supply important storefront context. Consistent locale prefixes or appropriate separate domains help avoid session and route conflicts when supporting multiple locales on one host.
Do FastStore and Store Framework translate text identically?
No. Their CMS and frontend internationalization workflows differ, and FastStore v4 Localization has release-specific requirements. Check the exact deployed technology.
Are checkout and My Account automatically translated?
Do not assume full coverage. VTEX documents differences in order-placed and transactional text versus My Account product information, which may need customization.
What should a team test before launch?
One real product from search to cart, approved checkout and notification, plus unavailable SKU or invalid address, a direct localized URL, SEO metadata and accessibility.
VTEX official documentation and connected translation learning
VTEX October 27, 2026 Catalog Multi-Language API release note; VTEX Catalog Multi-Language Integration Guide; VTEX Implementing Internationalization; VTEX Cross-Border Stores; VTEX FastStore Localization and Availability. Feature status, requirements and endpoints should be checked against the current account and documentation at implementation time.
For general principles of translating meaning correctly, see Master Art of Translation | The Complete System for Moving Meaning Between Languages and the Translate Like a Pro | Series Index.