Localization

The cart can be translated in any languages. Our language files are open source on GitHub.

We maintain the en translation. If you want to submit a new translation, use the en one as a baseline.

Each language file is a simple JSON document.

Default behavior

The cart will always try to load the right language file based on the lang attribute in the <html> tag of your site:

<!DOCTYPE html>
<html lang="fr">
    <head>
        <title></title>
    </head>
    <body>
    </body>
</html>

​​In the example above, the cart will try to load the fr.json language file. If it exists, the cart will be displayed in French. We automatically fallback to English.

Usage in theme

​​In any overridable component of the cart theme, you have access to a method named $localize. This method takes one parameter: the locale key.

For example:

Language file en.json:

{
    "actions": {
        "continue_shopping": "Continue shopping",
        ...
    },
    ...
}

Overridable component:

<h1>{{ $localize('actions.continue_shopping') }}</h1>

Output:

<h1>Continue shopping</h1>

Using our JavaScript API

​​You can also set the cart language using our JavaScript API.

This is possible via the session API:

<script>
    document.addEventListener('snipcart.ready', () => {
        Snipcart.api.session.setLanguage('fr');
    });
</script>

The example above will set the cart language to French.

You can also change labels with the JavaScript API. Let's say you want to change Continue shopping to Go back to store:

<script>
    document.addEventListener('snipcart.ready', () => {
        Snipcart.api.session.setLanguage('en', {
            actions: {
                continue_shopping: "Go back to store"
            }
        });
    });
</script>

​​This will only replace this specific label. It can come in handy when fine-tuning your Snipcart integration.

​​You can also use the JavaScript API to register extra locales. This will allow your translation to cover new labels you have added to our default theme, for instance.

How to contribute

To submit a new translation, you'll need to open a pull request. To do so, start by forking our repository. Open the repository on GitHub, then hit the Fork button. This will create a copy of the repository under your GitHub account.

Once the repository is forked, clone it on your computer. Open the project with your favorite code editor. You’ll see a folder named locales—it contains the language files.

A language file is a JSON document that contains all the labels used throughout the cart. ​​To add a new language, create a new file in this folder. The file should be named with the locale ISO code—for instance en.json for English, or fr.json for French.

Translate all the values in this file, and then commit and push your changes to your repository. Then, you will be able to open a pull request. On our side, we'll review the pull request and merge it if everything looks fine.

Please refer to this article about how forks and pull requests work on Github.

Regional locales

Sometimes, depending on where you're located, some wording might change. For example, some English words and expressions are different in the UK than in the US, so you might want to use a regional location file, like en-GB, for instance.

When you create a regional locale, you can override only necessary locales, you don't need to rewrite the whole file. Our building process will make sure to merge everything together. Here's an example of what we did for the fr-FR regional locale:

{
    "actions": {
        "continue_shopping": "Continuer les achats"
    }
}