All Tutorials

Locale files

All Tutorials

Locale files

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.

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. Scroll down the sidebar and click Locales, then click Add a new locale.

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

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

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.

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

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.


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 rendered by the time_tag and date filters should use the provided format options. These formats are displayed in the appropriate format for a storefront's language.


{{ order.created_at | date: format: 'abbreviated_date' }}


Dec 31, 2018

Custom date formats

You can create custom date formats with the format parameter in your locale files. These custom formats are defined under a date_formats parameter.

For example, create a new month_and_year custom format in locales/en.json. These custom formats use the same parameters as Ruby's strftime method. You can find a list of shorthand formats in Ruby's documentation or use a site like

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


{{ order.created_at | date: format: 'month_and_year' }}


December 2018