Localization guide

The practical version of International. Read this when you are adding a language or translating the theme yourself.

File structure

locales/
`-- en.default.json      Source strings - never translate this
|-- fr.json
|-- de.json
`-- es.json

Each file is a flat JSON object of key — string.

{
  "general": {
    "cart": "Cart",
    "menu": "Menu",
    "search": "Search"
  },
  "cart": {
    "in_cart_one": "%{count} item in cart",
    "in_cart_other": "%{count} items in cart",
    "empty": "Cart is empty"
  },
  "accessibility": {
    "open_cart": "Open cart",
    "open_menu": "Open menu"
  }
}

Key conventions

Convention	Meaning
`namespace.topic`	Grouping. `general`, `product`, `cart`, `header`, `footer`, `accessibility`
`_one` / `_other` suffix	Plural forms. Shopify picks based on `cart.item_count`
`%{count}`	The interpolated number
`accessibility.*`	Screen-reader labels. Always write these — they are the least visible and the most important

The accessibility namespace holds every aria-label in the theme. A merchant who translates the visible strings but not these ends up with a page where a screen-reader user hears English button names. It is the most commonly missed part of a translation.

Adding a language

Create the language in Shopify

Settings → Languages → Add language. Pick the language and the domain it will be served on.

Create the locale file

Copy locales/en.default.json to locales/<code>.json — for example locales/fr.json.

Translate every value

Keep the keys identical. Change only the values.

Push the theme

shopify theme push --store your-store.myshopify.com

Shopify copies the theme’s locale files into the new language.

Copy the locale in the admin

Settings → Languages → your language — Actions → Copy from default theme. This picks up any keys added since the theme was first published.

Verify the language selector

It appears in the header automatically once the second language is published.

Using a translation in Liquid

{%- comment -%} Simple {%- endcomment -%}
{{ 'general.cart' | t }}

{%- comment -%} With a placeholder {%- endcomment -%}
{{ 'cart.in_cart_other' | t: count: cart.item_count }}

{%- comment -%} In an attribute {%- endcomment -%}
<button aria-label="{{ 'accessibility.open_cart' | t }}">…</button>

{%- comment -%} In JavaScript, via a data attribute {%- endcomment -%}
<button
  data-announcement-empty="{{ 'cart.empty' | t }}"
  data-announcement-one="{{ 'cart.in_cart_one' | t }}"
  data-announcement-other="{{ 'cart.in_cart_other' | t }}"
>

Right-to-left languages

The theme’s layout uses logical CSS properties and flexbox, so RTL mirrors automatically. The header, the cart drawer and the mobile drawer all slide in from the correct edge.

Directional icons need an RTL variant. If you add a chevron that points “forward”, add .icon--rtl { transform: scaleX(-1); } and apply it inside an [dir="rtl"] selector.

Regional formats

Thing	Handled by
Date format	Shopify’s `date` filter, using the storefront locale
Number format	Shopify’s money filter, using the storefront locale
Currency symbol and position	Settings → Markets
Address formats	Shopify’s markets settings
Phone number format	Settings → Markets

Only the strings in locales/ are yours to translate. Formats are Shopify’s job, and they follow the storefront locale automatically.

Adding a language in code

If you deploy with the CLI, the flow is:

# 1. Create the locale file
cp locales/en.default.json locales/fr.json

# 2. Translate it (any editor, any tooling)

# 3. Push
shopify theme push --store your-store.myshopify.com

# 4. In the admin, copy the locale from the default theme

After every theme update, re-copy the locale in Settings → Languages. New keys added by the update are not present in your existing translated files, and they will silently fall back to English.

International

The feature overview.

Code reference

The full file map.

Getting Started

Theme Configuration

Sections & Blocks

Features

Going Further

Resources

Localization guide

Localization guide

File structure

Key conventions

Adding a language

Using a translation in Liquid

Right-to-left languages

Regional formats

Adding a language in code

International

Code reference

​Localization guide

​File structure

​Key conventions

​Adding a language

​Using a translation in Liquid

​Right-to-left languages

​Regional formats

​Adding a language in code

International

Code reference

Localization guide

File structure

Key conventions

Adding a language

Using a translation in Liquid

Right-to-left languages

Regional formats

Adding a language in code