Translating a Shopify theme and its content

A second language on Shopify rarely fails completely. It fails in patches: a translated product page with an English “Add to cart”, a translated home page with an untranslated banner, an Arabic menu with an English size guide. Each patch comes from a different layer of the store, and each layer is translated in a different place.

The four layers of a translated store

The language has to exist first. Under Settings > Languages you add it, choose the domains it appears on, add translations and publish it. Stores on Basic to Advanced plans can publish up to 20 languages; Plus and Enterprise stores up to 30. Each published language gets a subfolder, such as /fr, or a subdomain.

Theme strings: the locale files

A theme keeps its interface text in JSON locale files in its locales directory. The default language file is named like en.default.json, and other languages use IETF language tags, such as fr.json or es-ES.json. Templates don’t contain the text itself; they call a key through the t filter:

{{ 'products.product.add_to_cart' | t }}
{{ 'layout.header.hello_user' | t: name: customer.first_name }}

The t filter also handles pluralization through a count attribute with the Unicode CLDR categories (zero, one, two, few, many, other). That matters beyond English: some languages have more plural forms than “one” and “other”, and a theme that builds plurals by hand gets them wrong.

Merchants reach these strings through Shopify’s language editor, Translate & Adapt, a CSV import or a third-party app. Two limits are worth knowing. Each locale file can store up to 3,400 translations. And if a field is left without a translation, the theme’s default language is shown, which is where most stray English on a translated page comes from.

Why some text can’t be translated at all

Text typed directly into a template or snippet, instead of a locale key or a section setting, has no translation key. No translation tool can reach it, and it shows in every language. Custom themes and themes edited over years are the usual source. The fix is in the code: move each string into the locale files and output it with t, or into a section setting that can be translated. Locale keys follow a three-level structure (category, group, description), and descriptive keys such as blogs.article_comment.submit_button_text tell a translator where the text appears, which cuts down on wrong translations.

Links are the same kind of problem. Shopify’s theme guidance is to avoid hard-coded paths and build URLs from Liquid objects or the routes object, and from window.Shopify.routes.root in JavaScript. A hard-coded /collections/sale link on a French page sends the visitor back to the default language.

Store content: Translate & Adapt and imports

Shopify’s Translate & Adapt app translates products, collections, blog posts, policies and pages, and can adapt content per market, for example a different message for one region. It offers automatic translation for a maximum of 2 languages. Policies aren’t translated automatically and have to be translated by hand.

When source content changes after an automatic translation, the translation is marked out of sync and is refreshed the next time you run Auto-translate. Translations you added or edited manually aren’t overwritten. Plan who owns that step: a product description edited in the default language stays out of date in every other language until someone acts.

Some content can’t be translated with the app: collection filters, forms made with the Shopify Forms app, manual payment method instructions, product images and tags. Product, article and blog tags can’t be translated at all, which matters for themes that show tags to customers, for example as filter labels. For large catalogs, CSV export and import or a third-party app are the alternatives.

When translating HTML or Liquid content, translate only the visible text. Keep HTML tags, link destinations and symbol codes, and never translate Liquid tags inside {{ }} or {% %}.

Checkout and apps

Checkout text is edited from Settings > Checkout with Edit checkout content. If the store is translated, update the translations whenever you change the default checkout text, or the other languages keep the old wording. Shopify provides pre-translated checkout text for 33 languages; for a language outside that list, checkout and system messages have to be translated manually through the language editor.

Apps are the layer that gets forgotten. Some app content is outside Translate & Adapt’s reach, so each app shown on the storefront needs checking in every language. An app with no language support may need replacing, or its storefront piece rebuilt in the theme.

The language selector

Customers need a way to switch. In a Liquid theme, the language selector sits inside a localization form, submits a language_code field and lists localization.available_languages. Shopify’s guidance is to show it only when more than one language is available.

Keeping translations up to date

Translation is not a one-off job. Every new product, page, section or theme update adds text in the default language, and nothing stops it from going live untranslated. Three habits keep a multilingual store consistent:

• One owner per language. Someone checks new and changed content in each language on a fixed schedule, for example before each campaign.
• Theme updates get a translation pass. A theme update can add new text, and any string without a translation falls back to the default language, so check each language after updating.
• Developers add keys, not text. Any new section or snippet should use locale keys with the t filter from the start, including plural forms and dates. Locale files can also define date_formats, which must exist in every locale file or the page renders a Liquid error, and keys ending in _html render their HTML instead of escaping it.

A translation checklist

1. Search the theme for text hard-coded in templates and snippets; move it to locale keys or settings.
2. Replace hard-coded links with Liquid URLs or routes.
3. Add and publish the language, then translate the theme’s strings in the language editor and fill every gap.
4. Translate store content with Translate & Adapt, an import or your translator, and review what was machine translated.
5. Translate policies by hand, and update checkout text translations.
6. Check every app on the storefront in each language.
7. Walk through the store in each language on a phone: home, collection, product, cart, search, account and emails.

Right-to-left languages add a layout layer on top of all this. For Arabic, see selling in Arabic on Shopify.