Locale files are JSON files that contain a set of translations for text strings used throughout the theme, and there are two types:

  • Storefront - These have a .json extension, and control storefront translations.
  • Schema - These have a .schema.json extension, and control schema translations.

Locale files are hosted in the locales directory of a theme.

Structural overview

Both locale file types follow the same general format of being organized into the following levels:

  • Category: The top-level category of your translations. For example, general contains general translations.
  • Group: The second level grouping of translations within a category. For example, 404 contains general translations related to the 404 page.
  • Description: The third level, which represents the individual translations. For example, title contains the title of the 404 page

How to create locale files

There are two ways to generate a locale file:

Add a new locale

To add a new locale through the code editor:

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

  2. From the dropdown, choose an existing locale file as a starting point, or start a new one from scratch.

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

Manually create a locale

You can create a locale file in your local development environment. When you manually create a locale file, you need to make sure of the following:

  • Your files are named appropriately. Refer to Name locale files for more information.
  • The files are added to the locales directory of theme.

Name locale files

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.

For example:

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

If a language isn’t region specific, you can use only the 2-letter lowercase language representation. For example:

  • fi.json for Finnish - All regions

The 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.

Most themes use en.default.json, which sets the default locale of the theme to English.