---
url: https://developer.youcan.shop/themes/locales/storefront-locale-files.md
---
# Storefront Locale Files

Storefront locale files have a `.json` file extension, and control translations for storefront content. These translations can be edited by sellers through the theme's language editor.

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

## Location

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

```bash
└── theme
    ...
    ├── config
    └── locales
      ├── en.default.json
      ├── ar.json
      ...
```

## Schema

Locale files need to follow a specific [naming structure](#file-naming). They also follow a basic organizational structure:

* **Category**: The top-level category of your translations.
* **Group**: The second level grouping of translations within a category.
* **Translation**: The third level, which represents the individual translations.

```json
{
  "my_category": {
    "my_group": {
      "my_translation": "translation text",
      // ...
    },
    // ...
  },
  // ...
}
```

## File Naming

You can use the 2-letter lowercase language representation to name your locale files.

| Language | Format |
|----------|--------|
| French  | `fr.json` |
| English | `en.json` |
| Arabic | `ar.json` |

Additionally, you must designate a [default locale file](#default-locale-file) for each type.

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

|  Example   |
|------------|
| `en.default.json` |

## Usage

When working with storefront locale files, you should familiarize yourself with [referencing schema translations](#reference-schema-translations).

### Reference schema 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](/themes/filters/localization/translate) (`t` filter).

For example, let's assume you have locale files for English, Arabic, and French. In this case, you might have the following in each associated locale file:

:::code-group

```json [en.default.json (English)]
{
  "cart": {
    "page": {
      "title": "Shopping Cart"
    }
  }
}
```

```json [ar.json (Arabic)]
{
  "cart": {
    "page": {
      "title": "عربة التسوق"
    }
  }
}
```

```json [fr.json (French)]
{
  "cart": {
    "page": {
      "title": "Panier"
    }
  }
}
```

:::

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

```liquid
<span>{{ "cart.page.title" | t }}</span>
```

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

```html
<!-- English -->
<span>Shopping Cart</span>

<!-- Arabic -->
<span>عربة التسوق</span>

<!-- Frenhc -->
<span>Panier</span>

```

### Placeholder Replacement

Translation strings can use placeholder symbols to insert dynamic values when displayed.

Include the `%` symbol or any symbol in your locale file as a placeholder:

:::code-group

```json [/locales/en.default.json]
{
  "layout": {
    "header": {
      "hello_user": "Hello %!"
    }
  }
}
```

:::

When referencing the translation in your theme, use the `replace` filter to substitute the placeholder:

```liquid
{{ 'layout.header.hello_user' | t | replace: '%', 'Mark' }}
```

This outputs:

```text
Hello Mark!
```