Handling internationalization with the Localization feature

This feature is currently in Closed Beta. If you're interested in using this feature in your store, contact the VTEX Support team.

The Localization feature enables stores to provide a tailored shopping experience for a global market. By focusing on language, region, and currency, you can build a localized store ready for international sales with multiple languages and currencies.

In this guide, you'll learn how to implement the Localization feature in your FastStore project.

Before you begin

Enable the CMS

The Localization feature works in combination with the CMS. Make sure the CMS is installed and enabled in your account.

This feature isn't available for Headless CMS (legacy).

Use the Catalog Multi-Language API for Intelligent Search translation

To retrieve translated catalog data, FastStore uses Intelligent Search to fetch localized content. To use a complete catalog translation solution, update your store to use the Catalog Multi-Language API.

For detailed instructions on consuming localized data, implementing the feature, and activating it for your store, please see the Implementation by Storefront type guide.

Upgrade to FastStore V4

After enabling the CMS, you must upgrade your FastStore version to v4. To do so, follow the Upgrading FastStore to v4 guide.

Instructions

Step 1 - Configure secrets in WebOps

To allow the platform to access your store's bindings, you must configure WebOps secrets:

Create the following keys by following the instructions in Managing API keys:
- VTEX_ACCOUNT={accountName}
- FS_DISCOVERY_APP_KEY={appKey}
- FS_DISCOVERY_APP_TOKEN={appToken}
Add the created keys to WebOps by following the instructions in Creating variables and secrets.

Step 2 - Configure store bindings

A binding is the association between a specific domain URL and its locale and currency. The currency is defined by the sales channel associated with the binding. Sales channels also define different catalogs and pricing for each binding. Content settings are applied when a user accesses a particular domain. Configuring store bindings ensures a localized experience.

Open a ticket with VTEX Support to set up your bindings. In the ticket, include the following information:

Account name
Domains
- Domain URL
  - Associated sales channels and currency
  - Associated locale

Example:

Account name: storename
Domain URLs
- www.storename.com/pt-br
  - Associated sales channels and currency: Sales Channel 1, Currency: Real
- www.storename.com/en-us
  - Associated sales channels and currency: Sales Channel 2, Currency: Dollar
  - Associated locale: en-US
  Changes to bindings only take effect after the next store build. Also, even if a binding is configured with multiple locales, FastStore only considers the default locale.

Step 3 - Enable the `localization` flag in `discovery.config.js`

To enable the localization feature, add the localization flag to the [discovery.config.js](http://discovery.config.js) file.

Open your FastStore project in your preferred code editor.
Open the discovery.config.js file and add the following:

_10... _10localization: { _10 enabled: true, _10}, _10...
Add the contentSource object to make sure your project will sync with the CMS:

_10... _10contentSource: { _10type: "CP", _10}, _10...

Make sure you have enabled the CMS.

Step 4 - Enable the flag in the CMS

In the VTEX Admin, go to Storefront > All content.
Click Global Section Content Type.
In the Navbar section, under Navigation > Localization Button, activate the “Should display localization button?” field.

Step 5 - Test the feature locally

Before pushing the changes you made in the previous steps to production, test the Localization feature locally.

In your FastStore root project, create the .vtex.env file and add the keys created in Step 1: Setting up secrets on WebOps:

_10VTEX_ACCOUNT={accountName} _10FS_DISCOVERY_APP_KEY={appKey} _10FS_DISCOVERY_APP_TOKEN={appToken}
Run yarn dev.
Open the localhost and test if the locales are working.
Deploy the changes.

Testing locally with subdomains

To test subdomain-based locales locally, you need to map the domains to your machine's hosts file.

Open the hosts file in your terminal:

macOS and Linux
Windows

Mac/Linux
Add new lines at the end of the file, mapping each domain to 127.0.0.1. For example:

_10127.0.0.1 brandless.fast.store.com.br _10127.0.0.1 pt.brandless.fast.store _10127.0.0.1 brandless.fast.store.com.br/pt-BR

Each line follows the format: <IP address> <domain>. In the example above:
- 127.0.0.1 points to your local machine.
- The domains are the subdomains you want to test locally.
Save the file.
Start your FastStore project locally.
Open one of the configured domains in your browser, for example http://pt.brandless.fast.store:3000. This will resolve to your local environment.
Once you finish testing, you can remove these entries from the hosts file.

After completing these steps, you can enable your store locales by following the instructions in Configuring store locales.