Localization Tutorial

You can localize your Stencil theme for your desired target language. This tutorial describes how to localize a storefront in Spanish. By following this method, you can display a specific language based on the language selected in the viewer's browser. By the end of this tutorial, you will have the tools to localize most areas of your theme.

Prerequisites

In this tutorial, we will use Stencil CLI and Browsersync (opens in a new tab) to serve up a live preview of a theme in development.

To complete this tutorial, you should be familiar with the following concepts:

Adding a language file

After downloading and extracting your Stencil theme, open the folder containing your theme files and navigate to the /lang subfolder.

The /lang subfolder includes the en.json file and example language files. The en.json file and your language file must be present for a localized Stencil theme to work. Each language requires its own JSON file.

Name your translation file es.json and save it in the /lang subfolder. Translation files are named based on the BCP 47 specification (opens in a new tab) of language and region codes.
Copy the desired key-value pairs from the en.json file and paste them into your newly-created es.json file. Update the values to create your language file.

en.json

{
"header": {
  "welcome_back": "Welcome back, {name}",
  "skip_to_main": "Skip to main content"
   },
 }

es.json

{
"header": {
  "welcome_back": "Bienvenidos, {name}",
  "skip_to_main": "Saltar a la principal"
   },
 }

Creating translation keys

Perform the following steps to create new key-value pairs and invoke a defined translation key.

Add a key-value pair to a language file.

In en.json, add new_hours key and corresponding information for the value.

"header": {
        "welcome_back": "Welcome back, {name}",
        "skip_to_main": "Skip to main content",
        "new_hours": "Summer hours: {hours}"
    },

In es.json, add the same new_hours key and the Spanish translation of the value.

"header": {
        "welcome_back": "Bienvenidos, {name}",
        "skip_to_main": "Saltar a la principal",
        "new_hours": "Horario de verano: {hours}"
    },

Use the Handlebars lang directive in the appropriate file to show a translated string.

For this example, update /templates/components/common/header.html using the code below. Add the code after the {{/if}} tag and before the <header> tag.

{{/if}} 
{{> components/common/alert/alert-success (lang 'header.new_hours' hours="8 AM to 5 PM Central" ) }}
<header class="header" role="banner">

Updating browser settings

Update your language browser to display the translation on the storefront. The following steps are for the Chrome browser.

In your browser, go to Settings > Advanced.
Select Languages.
Expand the language dialog and click Add languages.
Select your desired language and click Add.
Drag the newly selected language to the top of the list.
Refresh your browser to see the translations.

Other browsers may look and act differently. We suggest previewing your site to ensure the localization is working as expected.

Related resources

Did you find what you were looking for?

Using translation keys Storefront selector