localize Filter

Used to render translations files in the theme/translations directory. You must provide .json translation files named after the Square Online locales you want to support (e.g. “en_US.json”, “en_GB.json”).

If we can’t find a matching .json translation file on the locale, we’ll try falling back to your site locale. If no match is found for that locale, we simply fallback to the first available .json translation file.

If no match for the key is found based on a matching .json translation file, we’ll attempt to find a fallback translation key match using the same logic above. If no match is found, an empty string is displayed.

Note: In preview mode, instead of an empty string, we will display “« localize: {{key}} »” to simplify localization debugging.

The localize filter can take in a localization source property. The filter will try to load the .json file that matches the source’s locale.

<div>{{ 'differentSource' | localize([], 'SITE') }}</div>

theme/translations/en_US.json

{
    "hello": "Hello",
    "helloMultiple": "Hello {{0}} and {{1}}",
    "helloMultipleNamed": "Hello {{name1}} and {{name2}}",
    "nested": {
        "hi": "Hi"
    }
}

Code

<div>{{ 'hello' | localize }}</div>
<div>{{ 'helloMultiple' | localize([ 'Tim', 'Brady' ]) }}</div>
<div>{{ 'helloMultipleNamed' | localize({ name1: 'Tim', name2: 'Brady' }) }}</div>
<div>{{ 'nested.hi' | localize }}</div>

Output

Hello
Hello Tim and Brady
Hello Tim and Brady
Hi

If you want to bind site data in one of your localize properties, you can use site_data(x.y.z). If no match is found, an empty string is returned. Note that you can use \ to escape if you want to use the literal string.

<div>{{ 'helloMultiple' | localize({ name1: 'site_data(x.y.z)', name2: 'site_data(a.b.c)' }) }}</div>

If you want to bind a string assembled in JS, you’ll need to do the replacement yourself in your script.

const assembledString = `${firstName} ${lastName}`;
const translation = '{{ 'helloName'|localize({ name: '{name}' }) }}';
const assembledTranslation = translation.replace('{name}', assembledString);