Internationalization prepares your store to operate in multiple languages by translating storefront content and catalog data and applying regional formatting. When your business requires multiple currencies, prices, or logistics per market, pair internationalization with a cross-border setup that uses different trade policies.

In this guide, you'll learn how to start implementing internationalization in your store, including:

• Store architecture: Define your operation and the architecture that best fits your business needs.
• Quickstart: Discover the initial steps to internationalize your store.
• Fundamental tools: Set up the tools you must have for your internationalized operation to work correctly.

Internationalization is available for Store Framework and for FastStore through the Localization feature in FastStore v4. FastStore Localization is in Closed Beta. To request Localization access or set up a multistore environment, open a VTEX support ticket.

Before implementing internationalization in your store, make sure you have the following information ready:

• Target languages/locales: List languages with curated translations and those relying on automatic translation, considering audience and SEO.
• Translation scope: Distinguish storefront content (messages from React apps or CMS content) from Catalog content (names, descriptions, meta fields), as each layer has different tools and flows depending on your storefront.
• Currencies and regional formatting: Confirm whether you only need language changes or also require the display of prices and regional formats (dates, numbers) per locale.
• URLs and SEO: Determine whether you'll have localized paths/hosts per language (for example, /en, /pt) and whether you need to declare alternate or hreflang tags between versions for search engines.

If you only need to offer the same product in multiple languages, you can implement internationalization without changing your current architecture. Multi-language support is available for Store Framework and for FastStore via the Localization feature.

However, if your operation involves different currencies, prices, payments, or logistics across countries or regions, integrate internationalization with a cross-border strategy. Learn more in the guide Implementing cross-border stores.

To start implementing internationalization, configure the binding. The steps differ by storefront technology.

A binding represents a storefront surface that combines a domain (canonical base address), locale, currency, and the sales channels (trade policies) it serves. This configuration is key for operating multiple languages within a single VTEX account.

To internationalize your Store Framework store, configure the binding to use your final public domain as the canonical base address. In multi‑locale setups, use consistent paths per locale when sharing the same host (for example, /en, /pt). See the instructions below:

1. Access {accountName}.myvtex.com/admin/binding. Replace {accountName} based on your scenario.
2. Click the vertical ellipsis menu (⋮) alongside the canonical address you want to configure, then click Edit.
3. Set the canonical base address to your public domain (and the locale path, if applicable).
4. Go to Locales and click + Add to add a new locale.
5. Click Save to save the changes.

Best practices on binding configuration

In a multi-locale setup on the same host, make each locale's canonical base address follow the same structure, typically with a path prefix for all locales (for example, store.com/en, store.com/pt), instead of mixing root for one locale and paths for others. This avoids conflicts in session cookies and redirects between locales.

When one locale is at the root (store.com), and another is under a path (store.com/pt), users can end up with two segment cookies: One scoped to / and another to /pt, which leads to conflicting session information and erratic behavior during language switches. Using paths in both locales avoids this duplication.

✅ Do

Use a path prefix for every locale on the same host or use separate domains for each locale:

• Example with paths for all locales on the same host:

  en-US: https://store.com/en

  pt-BR: https://store.com/pt

• Example with different domains per locale:

  en-US: https://en.store.com

  pt-BR: https://pt.store.com

❌ Don't

Avoid mixing a root URL for one locale with a path prefix for another:

en-US: https://store.com/

pt-BR: https://store.com/pt

In FastStore, bindings are configured through VTEX Support. Each domain is associated with a sales channel (currency, catalog, and pricing) and a locale. Even if a binding is configured with multiple locales, FastStore only considers the default locale.

After bindings are set up, enable Localization in your project by:

1. Configuring WebOps secrets so the platform can access your store's bindings.
2. Enabling the localization flag in discovery.config.js.
3. Activating the localization button in the CMS Navbar.

For the full implementation, including prerequisites such as FastStore v4 and the CMS, see Handling internationalization with the Localization feature.

The tools you need depend on your storefront technology. Catalog translation applies to both Store Framework and FastStore.

• Catalog translation: To translate catalog information (categories, products, SKUs, brands, specifications, and collections) and override the automatic translation, we recommend using the Catalog Multi-Language API. It provides granular control over translations for products, SKUs, categories, brands, and other entities, while integrating natively with Intelligent Search and supporting Translation Management Systems (TMS). To learn how to implement it, see the Catalog multi-language integration guide, including the implementation by storefront type.

  Product information on the Order Placed pages and in transactional emails is automatically translated. On the My Account page, product information isn't translated automatically and may require additional customization.

  The simultaneous use of both the Catalog Multi-Language API and the GraphQL catalog translation flow isn't supported for catalog entities. Once the Catalog Multi-Language feature is activated, you'll no longer be able to manage catalog translations using GraphQL. For stores that still use the legacy GraphQL translation flow, see Translating Catalog content.

• Messages: In Store Framework projects, translations for store components are stored in a "/messages" folder located within the app's root directory. Thus, the translation of the content involves declaring the translated content for each language (binding) and for each element to be rendered via GraphQL. In this case, especially for specifications, breadcrumbs, and filters, the translation must be done using the Messages app. Learn more in the guides Translating storefront content and Overwriting the Messages app.
• Locale Switcher: Allows switching languages on the site.

FastStore supports multi-language stores through the Localization feature (Closed Beta). Requirements and setup include:

• FastStore v4: Required for Localization.
• CMS: Localization works with the CMS and isn't available for Headless CMS (legacy). Storefront content is managed per locale in the CMS.
• Bindings and sales channels: Each domain is associated with a sales channel and a locale. Configure bindings with VTEX Support, then enable the localization flag in discovery.config.js and the localization button in the CMS Navbar.
• Catalog Multi-Language API: FastStore retrieves translated catalog data through Intelligent Search. Use the Catalog Multi-Language API for a complete catalog translation solution.

For the full implementation, see Handling internationalization with the Localization feature.