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 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 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 404.liquid template:

<h1>{{ 'general.404.title' | t }}</h1>
<p>{{ 'general.404.subtitle' | t }}</p>

The example above contains the following translation keys:

  • general.404.title
  • general.404.subtitle

The following is how those same keys appear in a locale file:

  "general": {
    "404": {
      "title": "Page not found",
      "subtitle": "Sorry, we couldn't find this page."