Storefront locale files
Storefront locale files host translation strings for content displayed on the storefront throughout the theme. These translations can be accessed by merchants through the Shopify 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.
Storefront locale files have a
.json extension. Learn how to create and name locale files.
Basic key structure
In general, a translation key has the form of
1st-level.2nd-level.3rd-level, where each level of the key is associated with the following levels of the Shopify Language Editor hierarchy:
1st level- The translation category, which represents the top-level tabs.
2nd-level- The translation group, which represents the sections within the associated top-level tab.
3rd-level- The translation description, which represents the individual translations.
For example, you might have the following code in the
The example above contains the following translation keys:
The following is how those same keys appear in a locale file:
To ensure that translations are mapped correctly, and to keep the process as simple as possible for merchants, you should organize your key structure to reflect your theme structure. The first two levels of the structure might look like this:
|1st level||2nd level|
||404, breadcrumbs, search (results page and blank slates), pagination|
||article, article comments, blog sidebar|
||cart contents, updates, notes, link to checkout|
|collection, collection loop
||product, product loop, related products|
||general field titles and identifiers|
||account, orders (list and details), account activation, addresses, login, password, registration|
||contact form, form errors|
||blank slate, featured, help|
||title, usage terms|
Translation keys in snippets
If you use translations in snippets, then you should group them with the category most related to the snippet's role. For example, if you have a
related-products.liquid snippet, then any associated translations should be included in the products group.
Checkout and system messages
Shopify provides checkout and system messages in the following languages:
- Bulgarian (Bulgaria)
- Chinese (Simplified)
- Chinese (Traditional)
- Croatian (Croatia)
- Lithunian (Lithuania)
- Norwegian (Bokmål)
- Portuguese (Brazil)
- Portuguese (Portugal)
- Romania (Romanian)
Translation strings can be interpolated, meaning you can include variables in your strings to be dynamically populated when the string is referenced in Liquid. For example, you can include following in your locale file:
When you reference that translation in your theme, you can specify a value for the
In the case of a customer named "Jane", this code outputs the following:
Pass multiple arguments
With interpolation, it's possible to pass multiple arguments, separated by a comma (
,). For example, if you want to extend the example above to show the customer's first and last name, then you can adjust your translation string and theme reference to the following:
In the case of a customer named "Jane Doe", this code outputs the following:
Translated content is escaped by default, meaning any HTML character is converted into its entity equivalent.
The _html suffix
You can add the suffix
_html to the description level of your translation key to prevent translated content from being escaped. For example, the content output by the following translation would be escaped, causing the
<strong> tags to show as plain text:
_html suffix prevents the output content from being escaped, allowing the
<strong> tags to render as proper HTML:
You can apply locale-aware pluralizations to translations by passing a
count attribute to the translation filter (
The following pluralization keys, defined by the Unicode Consortium's CLDR, are supported:
For example, the following translation and translation reference returns the following output:
For more information about pluralization rules in different languages, refer to the Unicode language plural rules tables.
Date and time localization
For example, the following Liquid generates the following output:
You can include custom formats in locale files by adding a
Using the custom format above, the following Liquid generates the following output:
Reference storefront translations
For example, let's assume you have locale files for English, French, and Spanish. In this case, you might have the following in each associated locale file:
To reference this translation, you might use something like the following:
The output is customized based on the settings in each locale file: