Storefront Locale Files
Storefront locale files have a .json file extension, and control translations for storefront content. These translations can be edited by sellers through the theme's language editor.
Rather than hard-coded text strings, theme layouts, templates, snippets, and Liquid assets can reference these translations with the Liquid translation filter (t filter). This returns the appropriate translated string from the locale file for the active language.
Location
Storefront locale files are located in the locales directory of the theme:
└── theme
...
├── config
└── locales
├── en.default.json
├── ar.json
...Schema
Locale files need to follow a specific naming structure. They also follow a basic organizational structure:
- Category: The top-level category of your translations.
- Group: The second level grouping of translations within a category.
- Translation: The third level, which represents the individual translations.
{
"my_category": {
"my_group": {
"my_translation": "translation text",
// ...
},
// ...
},
// ...
}File Naming
You can use the 2-letter lowercase language representation to name your locale files.
| Language | Format |
|---|---|
| French | fr.json |
| English | en.json |
| Arabic | ar.json |
Additionally, you must designate a default locale file for each type.
Default Locale File
You must designate a default locale file in the format of *.default.json, where * is your selected language. This file contains the translations for the default language of the theme. Only one default file is permitted.
| Example |
|---|
en.default.json |
Usage
When working with storefront locale files, you should familiarize yourself with referencing schema translations.
Reference schema translations
To reference translations from the storefront locale file for your theme's active language, you can use translation keys and the Liquid translation filter (t filter).
For example, let's assume you have locale files for English, Arabic, and French. In this case, you might have the following in each associated locale file:
{
"cart": {
"page": {
"title": "Shopping Cart"
}
}
}{
"cart": {
"page": {
"title": "عربة التسوق"
}
}
}{
"cart": {
"page": {
"title": "Panier"
}
}
}To reference this translation, you might use something like the following:
<span>{{ "cart.page.title" | t }}</span>The output is customized based on the settings in each locale file:
<!-- English -->
<span>Shopping Cart</span>
<!-- Arabic -->
<span>عربة التسوق</span>
<!-- French -->
<span>Panier</span>Missing translations
If a key is not in the locale file of the active language, the t filter uses the default locale file. If the key is in neither file, the filter returns the key.
Interpolation
Translation strings can contain variables in double curly braces. Pass the values as named arguments to the t filter:
{
"layout": {
"header": {
"hello_user": "Hello {{ name }}!"
}
}
}{{ 'layout.header.hello_user' | t: name: customer.first_name }}Hello Mark!A variable that has no argument is kept as it is.
Pluralization
To change a translation with a number, make the key an object with one entry for each plural form, and pass count:
{
"cart": {
"items": {
"zero": "Your cart is empty",
"one": "{{ count }} item",
"other": "{{ count }} items"
}
}
}{{ 'cart.items' | t: count: cart.item_count }}The plural forms are zero, one, two, few, many and other. The form is selected with the plural rules of the locale file language. For example, Arabic uses all six forms, and English uses one and other. When count is 0 and the key has a zero entry, zero is used in all languages. If the selected form is not in the object, other is used.
HTML in translations
The t filter does not escape its output. A translation can contain HTML.