--- title: Storefront locale files description: About storefront locale files. source_url: html: https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files md: https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files.md --- ExpandOn this page * [Location](https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files#location) * [Schema](https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files#schema) * [Content](https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files#content) * [Usage](https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files#usage) # Storefront locale files 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 [Shopify Language Editor](https://help.shopify.com/manual/online-store/themes/customizing-themes/language/change-wording#overview-of-the-language-editor). Note Shopify provides [checkout and system message translations](#checkout-and-system-messages) through the Shopify Language Editor. However, this data is stored by Shopify outside of storefront locale files. Rather than hard-coded text strings, theme layouts, templates, snippets, and [Liquid assets](https://shopify.dev/docs/storefronts/themes/architecture#assets) can reference these translations with the Liquid [translation filter](https://shopify.dev/docs/api/liquid/filters/translate) (`t` filter). This returns the appropriate translated string from the locale file for the [active language](https://help.shopify.com/manual/online-store/themes/customizing-themes/language/translate-theme#choose-a-language-for-your-theme). When using the `t` filter, you can [interpolate](#interpolation) and [pluralize](#pluralize-translations) translations, as well as [localize any dates and times](#date-and-time-localization). *** ## Location Storefront locale files are located in the `locales` directory of the theme: ```text └── theme ... ├── config └── locales ├── en.default.json ... ``` *** ## Schema Storefront locale files need to follow a specific [naming structure](#name-structure). 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. * **Description**: The third level, which represents the individual translations. ## Example ```json { "my_category": { "my_group": { "my_description": "translation text", ... }, ... }, ... } ``` Tip When naming translation descriptions, try to be descriptive enough to give the translation context. For example, `blogs.article_comment.submit_button_text` gives more context than `blogs.article_comment.submit`. ### Name structure Locale file naming must follow the standard [IETF language tag nomenclature](https://en.wikipedia.org/wiki/IETF_language_tag), where the first lowercase letter code represents the language, and the second uppercase letter code represents the region. For example: | Language | Format | | - | - | | English - Great Britain | `en-GB.json` | | Spanish - Spain | `es-ES.json` | | French - Canada | `fr-CA.json` | If a language isn’t region specific, you can use the 2-letter lowercase language representation. For example: | Language | Format | | - | - | | Finnish - All regions | `fi.json` | Additionally, you must designate a [default locale file](#the-default-locale-file). #### The default locale file You must designate a default locale file in the format of `*.default.{% if include.parent == 'schema' %}schema.{% endif %}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.{% if include.parent == 'schema' %}schema.{% endif %}json`, which sets the default locale of the theme to English. *** ## 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, search (results page and blank slates), pagination | | `blogs` | article, article comments, blog sidebar | | `cart` | cart contents, updates, notes, link to checkout | | `collection` | collection, collection loop | | `products` | product, product loop, related products | | `layout` | general field titles and identifiers | | `customer` | account, orders (list and details), account activation, addresses, login, password, registration | | `contact` | contact form, form errors | | `home_page` | blank slate, featured, help | | `gift_cards` | title, usage terms | 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: * [referencing storefront translations](#reference-storefront-translations) * [interpolation](#interpolation) * [preventing translations from being escaped](#prevent-translations-from-being-escaped) * [pluralizing translations](#pluralize-translations) * [date and time localization](#date-and-time-localization) * [checkout and system messages](#checkout-and-system-messages) ### Reference storefront translations To reference translations from the storefront locale file for your theme's [active language](https://help.shopify.com/manual/online-store/themes/customizing-themes/language/translate-theme#choose-a-language-for-your-theme), you can use translation keys and the Liquid [translation filter](https://shopify.dev/docs/api/liquid/filters/translate) (`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: ## /locales/en.default.json (English) ```json { "blog": { "comment": { "email": "Your email" } } } ``` ## /locales/fr.json (French) ```json { "blog": { "comment": { "email": "Votre adresse courriel" } } } ``` ## /locales/es-ES.json (Spanish) ```json { "blog": { "comment": { "email": "Su correo electrónico" } } } ``` To reference this translation, you might use something like the following: ```liquid {{ 'blog.comment.email' | t }} ``` Tip When referencing translation keys in Liquid, they must be wrapped in single quotes (`'`). The output is customized based on the settings in each locale file: ## Output ```html // English Your email // French Votre adresse courriel // Spanish Su correo electrónico ``` ### 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 following in your locale file: ## /locales/en.default.json ```json { "layout": { "header": { "hello_user": "Hello {{ name }}!" } } } ``` When you reference that translation in your theme, you can specify a value for the `name` variable: ## /layout/theme.liquid ```liquid {% if customer %}