Storefront locale files
Storefront locale files are JSON files with a
.json file extension. They 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.
When using the
t filter, you can interpolate and pluralize translations, as well as localize any dates and times.
Storefront locale files are located in the
locales directory of the theme:
Storefront 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.
- Description: The third level, which represents the individual translations.
Name structureAnchor link to section titled "Name structure"
Locale file naming must follow the standard IETF language tag nomenclature, where the first lowercase letter code represents the language, and the second uppercase letter code represents the region.
|English - Great Britain||
|Spanish - Spain||
|French - Canada||
If a language isn’t region specific, you can use the 2-letter lowercase language representation.
|Finnish - All regions||
Additionally, you must designate a default locale file.
The default locale fileAnchor link to section titled "The default locale file"
You must designate a default locale file in the format of
* is your selected language. This file contains the translations for the default language of the theme. Only one default file is permitted.
Most themes use
en.default.json, which sets the default locale of the theme to English.
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.
For example, 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|
When working with storefront locale files, be aware of the following:
- referencing storefront translations
- preventing translations from being escaped
- pluralizing translations
- date and time localization
- checkout and system messages
Reference storefront translationsAnchor link to section titled "Reference storefront 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 (
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:
InterpolationAnchor link to section titled "Interpolation"
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 argumentsAnchor link to section titled "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:
Prevent translations from being escapedAnchor link to section titled "Prevent translations from being escaped"
Translated content is escaped by default, meaning any HTML character is converted into its entity equivalent.
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:
Pluralize translationsAnchor link to section titled "Pluralize translations"
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 localizationAnchor link to section titled "Date and time localization"
Dates and times can be rendered with the date and time_tag Liquid filters. Each has default format options that will display in the appropriate format for the store's active language:
datefilter default format options
time_tagfilter default format options
For example, the following Liquid generates the following output:
Custom formatsAnchor link to section titled "Custom formats"
You can include custom formats in locale files by adding a
These formats must use the same parameters as Ruby's
strftime method. You can find a list of these parameters in Ruby's documentation, or use a site like strfti.me.
Using the custom format above, the following Liquid generates the following output:
Checkout and system messagesAnchor link to section titled "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)