Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 61 · JavaScript, CSS and Design

Translations, Markets and Localization

Make a Shopify theme speak many languages and currencies: locale files, the t filter, plurals, schema translations, selectors, Markets and right-to-left.

A store that sells to one country in one language can get away with typing "Add to cart" straight into a template. The day the merchant turns on a second language, every hard-coded word becomes a bug. Shopify's answer is a translation system built into themes, combined with Markets, which decides which language, currency and prices a visitor sees.

As a theme developer you have two jobs. First, never leave visible text in your Liquid or JavaScript: move it into locale files and read it with the t filter. Second, make the parts of the page that depend on country and language (selectors, currency, text direction, links) behave correctly. This lesson covers both. It assumes you know Shopify filters and the global objects.

Locale files, Markets and the localization object exist only inside Shopify, so the theme code here is read-only and targets current Online Store 2.0 themes. The live examples re-implement the t filter, plural rules and a selector in JavaScript so you can see the logic. Which languages and countries are available depends on the merchant's settings and plan, so test with a real store.

Locale files

Every theme has a locales/ folder with one JSON file per language. The names follow a pattern:

TEXT
locales/
  en.default.json          storefront text for the default language
  en.default.schema.json   text used in the theme editor (setting labels)
  fr.json                  French storefront text
  fr.schema.json           French editor text
  ar.json
  de.json

The .default marker tells Shopify which language is the source: it is the fallback when another language misses a key. Storefront files hold what shoppers read; schema files hold what merchants read in the theme editor.

A storefront file is nested JSON:

JSON
{
  "products": {
    "add_to_cart": "Add to cart",
    "sold_out": "Sold out",
    "price_from": "From {{ price }}"
  },
  "cart": {
    "items": {
      "one": "{{ count }} item",
      "other": "{{ count }} items"
    }
  }
}

Keep keys grouped by area (products, cart, general) and name them for their purpose, not their English wording: products.sold_out, not products.sorry_none_left. The text can change; the key should not.

The t filter

In Liquid, translate with the t filter (short for translate):

LIQUID
<button type="submit">{{ 'products.add_to_cart' | t }}</button>
<p>{{ 'products.price_from' | t: price: product.price | money }}</p>
<p>{{ 'cart.items' | t: count: cart.item_count }}</p>
  • The left side is the key path, with dots for nesting.
  • Extra arguments (price:, count:) fill the {{ ... }} placeholders inside the translation.
  • Variables are escaped for you. A key whose name ends in _html is treated as trusted HTML, which lets a translator include a tag such as <a> or <strong>.
  • A missing key does not crash the page. Liquid prints a "translation missing" message instead, which is a loud, visible hint that a key is absent. Theme Check can also catch missing keys before you publish (see Theme Check, Linting and Testing).

Plurals

English has two forms ("1 item", "2 items"), but other languages have more. Shopify uses the count argument to pick a form from sub-keys named after the plural categories: zero, one, two, few, many and other. A language file only needs the categories that language uses. Arabic uses several, Japanese only other. The rule of thumb for you: never write {{ count }} item(s) or build the plural with an if; give translators a one and other (at least) and let them add the rest.

Translations in the schema

Section settings are labels the merchant sees, so they belong in the .schema.json files too. In a section's {% schema %}, replace plain text with a key prefixed by t::

JSON
{
  "name": "t:sections.hero.name",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "t:sections.hero.settings.heading.label",
      "default": "t:sections.hero.settings.heading.default"
    }
  ]
}

The matching entries live in locales/en.default.schema.json under the same path. This is more work than typing English, but it is required for Theme Store themes and makes the editor usable for non-English merchants. See Schema Settings in Depth.

Translations in JavaScript

JavaScript cannot call t. The usual pattern is to print the few strings a script needs into the page, either as data attributes or as a JSON blob, and read them from the script:

LIQUID
<script type="application/json" id="cart-strings">
  {
    "added": {{ 'cart.added' | t | json }},
    "error": {{ 'cart.error' | t | json }}
  }
</script>

Do not concatenate sentences in JavaScript ('You have ' + n + ' items'); word order differs between languages. Translate whole sentences with placeholders.

Try the t filter

This stand-in implements the heart of t: nested keys, placeholder filling, plural categories (using the browser/Node Intl.PluralRules), and a fallback to the default language. It is not Shopify's code; it shows the mechanism.

JS Stand-in: a t filter with plurals and fallback

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that fr has no sold_out key and quietly shows the English text, while an unknown key produces a visible "translation missing" message. In the Arabic column the count 11 uses a different form from 5, which a simple if (count === 1) could never express.

The localization object

The Liquid localization object describes the visitor's current language and country, and the ones they could switch to:

Property What it gives you
localization.language the current language (iso_code, name, endonym_name, root_url)
localization.country the current country (iso_code, name, currency)
localization.available_languages list of languages the shopper can choose
localization.available_countries list of countries (markets) the shopper can choose
request.locale.iso_code the language code of this request, such as fr or pt-BR

Use the first one in your layout so browsers and screen readers know the page language:

LIQUID
<html lang="{{ request.locale.iso_code }}" dir="{{ ... }}">

Language and country selectors

Switching language or country is done with a special form, {% form 'localization' %}. Shopify handles the redirect and cookies; you provide the inputs:

LIQUID
{%- form 'localization' -%}
  <label for="country">{{ 'general.country' | t }}</label>
  <select id="country" name="country_code" onchange="this.form.submit()">
    {%- for country in localization.available_countries -%}
      <option value="{{ country.iso_code }}" {% if country.iso_code == localization.country.iso_code %}selected{% endif %}>
        {{ country.name }} ({{ country.currency.iso_code }} {{ country.currency.symbol }})
      </option>
    {%- endfor -%}
  </select>
  <noscript><button type="submit">{{ 'general.update' | t }}</button></noscript>
{%- endform -%}

Language works the same way with name="language_code" and localization.available_languages. Two details deserve care. First, each option should be shown in its own language (an endonym: "Deutsch", "Français", not "German", "French"), so a shopper who landed on the wrong language can still find theirs. Second, auto-submitting on change hurts keyboard and screen-reader users, so offer a visible submit button, or at least keep the select usable without it (see Accessibility in Themes).

Markets and currency

A market is a merchant's rule set for a region: which countries belong to it, which languages and currencies it offers, domains or subfolders, and prices or taxes. Markets are configured in the admin, not in your theme. What your theme must do is not get in the way:

  • Print prices with the money filters. They convert and format for the visitor's presentment currency. Never concatenate '$' yourself.
  • Do not hard-code a currency symbol, a shipping threshold in dollars, or a country list. Read them from localization and shop objects.
  • Use {{ localization.country.currency.iso_code }} where a currency code is needed for display. If your JavaScript formats a price, take the currency and locale from the page, not from constants.
  • Remember that URLs change: a market may use a /fr or /de-ch path prefix. Use routes (for example routes.cart_url) and the root_url of the language instead of writing /cart. Hard-coded paths break in other markets.

Currency formatting also differs by language, not just by currency. The same amount reads 1,234.50 in one place and 1.234,50 in another. The second example below shows how Intl.NumberFormat copes with that.

Right-to-left languages

Arabic, Hebrew, Persian and Urdu run right to left. A solid theme needs only a few habits:

  • Put dir="rtl" on the html element for RTL languages (usually decided from the language code; check how your target theme exposes this).
  • Write CSS with logical properties: margin-inline-start instead of margin-left, padding-inline instead of padding-left and padding-right, text-align: start instead of left, inset-inline-end instead of right. The browser flips them automatically.
  • Mirror arrows and "previous/next" icons that imply direction, but not logos, play buttons or phone numbers.
  • Test with a long translation too: German and Finnish are far longer than English, so avoid fixed-width buttons.

More in CSS for Themes.

flowchart LR
  V["Visitor<br/>(country + language)"] --> M["Market rules<br/>(admin)"]
  M --> L["Language<br/>locales/fr.json"]
  M --> C["Currency<br/>money filter"]
  M --> U["URL prefix<br/>root_url, routes"]
  L --> P["Rendered page"]
  C --> P
  U --> P

The market chooses the language, currency and URLs; your theme reads them instead of assuming them.

Try a selector and formatter

This stand-in builds a localization-style object, renders a country selector as HTML text, formats a price with Intl.NumberFormat and decides the text direction. Real selectors post to Shopify; here the "form" only prints what it would send.

JS Stand-in: country selector, currency and direction

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output shows that currency symbols, decimal marks and even the position of the symbol vary. That is the reason to use Shopify's money filters (or Intl in scripts) and never string concatenation.

A localization checklist

  • No visible English in templates, snippets, JavaScript, aria-label, alt text or placeholder attributes.
  • Every t key exists in the default file; other languages may lag but fall back gracefully.
  • Plurals use count and the one/other pattern.
  • Schema labels use t: keys.
  • lang is set; prices use money filters; links use routes or root_url.
  • Layouts survive text that is 40% longer and flips right to left.

Check your understanding

Quick check · 4 questions

of 4 answered You scored / 4 · perfect!

  1. 1. What does the .default part in locales/en.default.json mean?

    The default locale is the source of truth. When another language is missing a key, Shopify falls back to the default file.
  2. 2. How should a cart item count be translated so that all languages work?

    Plural rules differ per language. Providing plural categories and passing count lets each language choose its own correct form.
  3. 3. Where do the labels merchants see in the theme editor get translated?

    Schema text lives in the schema locale files and is referenced with the t: prefix inside the section's schema.
  4. 4. Which CSS property is better for supporting right-to-left layouts?

    Logical properties follow the text direction automatically, so one rule works for both left-to-right and right-to-left pages.

Summary

  • Keep all visible text in locales/*.json, name keys by purpose, and read them with {{ 'key' | t }}.
  • Use count and plural sub-keys; never build plurals by hand.
  • Translate editor labels with t: keys in schema locale files.
  • Use localization, routes, root_url and the money filters instead of hard-coded languages, paths or currency symbols.
  • Set lang and dir, write CSS with logical properties, and design for longer text.

Next, make the whole theme fast in Theme Performance and Core Web Vitals.