Locale files

You must produce one locale file for each language or dialect that your theme supports, including checkout and system messages if the language is not supported by Shopify.

What's a locale file?

A locale file is a .json file that contains a set of translations for the text strings used in a theme template file. A separate locale file is used for every language that's available in the theme. Locale files are stored in the Locales section of the theme editor.

Instead of hard-coded text strings, theme template files use translation keys and pass them to the translation filter (or t filter.)

The translation filter retrieves the appropriate translated string from the locale file for the active language.


Shopify will accept an English-only theme with just an en.default.json locale file, provided it meets all the other requirements for internationalization. However, you should bear in mind that a theme with no translations won't be competitive with other internationalized themes.

Structural overview

Locale files are multi-level JSON objects containing key-value pairs organized in groups and sections:

  "general": {
    "404": {
      "title": "Page not found",
      "subtext": "Sorry, we couldn't find this page."
    "breadcrumbs": {
      "home": "Home",
      "products": "Products"
    "search": {
      "results": "Search Results"
    "search_blank_slate": {
       "title": "No search results",
       "subtext_html": "Your search for <strong>\"{{ terms }}\"</strong> did not yield any results. Try searching for something else."
    "pagination": {
       "summary": "Page {{ current_page }} of {{ pages }}",
       "previous": "Previous",
       "next": "Next"

Arrange the groups and sections in your locale files so that translation keys follow the structure of your theme.

How to create locale files

You can generate a locale file in a number of ways:

A new locale file is also produced when a new translation is created using the language editor.

Adding a new locale from the theme template editor

To add a new locale from the Edit HTML/CSS page:

  1. From your Shopify admin, click Online Store, and then click Themes (or press G W T).

  2. Find the theme you want to edit, click the ... button, and then click Edit HTML/CSS.

  3. Scroll down the sidebar and click Locales, then click Add a new locale.

    Add a new locale
  4. From the drop-down, choose an existing locale file as a starting point or create a new one from scratch.

  5. Enter a name for the locale file (without the .json extension), then click Create locale.


You must use the correct IETF language tag for your locale filename.

Creating a new locale file manually

If you create a locale file manually (that's outside the theme editor), be sure to use the correct IETF language tag for the filename.

Where to save your locale files

Save your locale files in the /locales folder, which is accessible from the Template Editor.

Locales folder

Naming locale files

When naming new locale files, you must follow the standard IETF language tag nomenclature, where the first lowercase letter code represents the language, and the second uppercase code represents the region, for example:

  • fr-CA.json for French - Canada
  • en-GB.json for English - Great-Britain
  • es-ES.json for Spanish - Spain

If a language isn’t region-specific, you can use only the 2-letter language representation of the IETF language tag, for example:

fi.json for Finnish - All Regions


Locale files created through the language editor are automatically named using the IETF nomenclature.

The default locale file

You must designate a default locale file, *.default.json. The default locale file contains the translations for the default language of your theme.


Only one default file is permitted, which by default is en.default.json (English.)


Values can contain HTML and Liquid objects (through interpolation.) You should limit the presence of these elements in the translation files, to ensure a simple translation process for merchants creating an additional language.

In some cases, you might have to include template elements in the values, to accommodate linguistic and grammatical differences, for example:


Posted by {{author}} on {{ date }}


Publié le {{ date }} par {{ author }}

Date localization

Dates passed through the date filter without any arguments are formatted with the default format for the current locale. For example:


<h1>{{ order.created_at | date }}</h1>


<h1>Fri, 25 Apr 2014 18:20:23 +0000</h1>

The date filter also accepts format options:

  • default
  • long
  • short.

For example:


<h1>{{ order.created_at | date: format: 'short' }}</h1>


<h1>25 Apr 18:25</h1>

Custom date formats

You can define custom date formats in your locale files.

For example:

This entry in locales/en.json:

  "date_formats": {
    "month_and_year": "%B %Y"

supplies the values for this entry in theme.liquid:

<h1>{{ order.created_at | date: format: 'month_and_year' }}</h1>

to return this output:

<h1>April 2014</h1>

Want to discuss this page?

Visit the Shopify Community