# Storefront locale files

> Storefront locale files hold the JSON translation strings a Shoplazza Theme outputs with the Liquid t filter, including file naming and value interpolation.

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 [Shoplazza Language Editor](../../developer-tools/language-editor).

:::note
Shoplazza provides checkout and system message translations through the Shoplazza Language Editor. However, this data is stored by Shoplazza outside of storefront locale files.
:::

Rather than hard-coded text strings, theme layouts, templates, and snippets can reference these translations with the Liquid [translation filter](/docs/theme/references/liquid/filters/localization#t) (`t` filter). This returns the appropriate translated string from the locale file for the active language.

When using the `t` filter, you can [interpolate](./storefront-locale-files#interpolation) translation.

## Location

Storefront locale files are located in the `locales` directory of the theme:

```text title="Directory"
└── theme
    ...
    ├── config
    └── locales
      ├── ar-SA.json
      ├── en-US.json
      ...
```

## Schema

Refer to [Locales Schema](/docs/theme/architecture/locales/overview#schema).

## Content

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                                                                  |
| :----------- | :------------------------------------------------------------------------- |
| `general`    | 404, breadcrumbs, pagination, search(result page and blank slates)         |
| `blogs`      | article, blog                                                              |
| `cart`       | cart contents, updates, notes, links to the checkout                       |
| `collection` | collection                                                                 |
| `products`   | product, related products                                                  |
| `customers`  | account, order(list and details), addresses, login, registration, password |
| `home_page`  | blank slate, featured                                                      |

:::note
If you use translations in snippets, then you should group them with the category most related to the snippet's role. For example, if you have a `related_products.liquid` snippet, then any associated translations should be included in the products group.
:::

## Usage

When working with storefront locale files, be aware of the following:

* [Reference storefront translations](./storefront-locale-files#reference-storefront-translations)
* [Interpolation](./storefront-locale-files#interpolation)

### 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](/docs/theme/references/liquid/filters/localization#t) (`t` 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:

```json title="/locales/en-US.json (English)"
{
  "products": {
    "product": {
      "sold_out": "Sold out"
    }
  }
}
```

```json title="/locales/fr-FR.json (French)"
{
  "products": {
    "product": {
      "sold_out": "Épuisé"
    }
  }
}
```

```json title="/locales/es-ES.json (Spanish)"
{
  "products": {
    "product": {
      "sold_out": "Vendido"
    }
  }
}
```

To reference this translation, you might use something like the following:

```liquid title="Input"
{{ 'i18n.products.product.sold_out' | t }}
```

The output is customized based on the settings in each locale file:

```html title="Output"
<!-- English -->
Sold out

<!-- French -->
Épuisé

<!-- Spanish -->
Vendido
```

### 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 the following in your locale file:

```json title="/locales/en-US.json"
{
  "products": {
    "product": {
      "save": "Save {{amount}}"
    }
  }
}
```

When you reference that translation in your theme, you can specify a value for the `amount` variable:

```liquid title="Input"
{{ 'i18n.products.product.save' | t: amount: 18.88 }}
```

In the case of this code outputs the following:

```html title="Output"
Save 18.88
```

#### 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 saved money's amount and symbol then you can adjust your translation string and theme reference to the following:

```json title="/locales/en-US.json"
{
  "products": {
    "product": {
      "save": "Save {{amount}}{{amount_symbol}}"
    }
  }
}
```

```liquid title="Input"
{{ 'i18n.products.product.save' | t: amount: 18.88, amount_symbol: '$' }}
```

In the case of this code outputs the following:

```html title="Output"
Save 18.88$
```