Localization & i18n in Shopify Themes

Shopify themes store translatable strings in locale files under locales/, typically en.default.json as the schema source plus additional language files such as hi.json or fr.json. Each key maps to merchant-facing and customer-facing copy: general.button_labels, products.add_to_cart, sections.header.settings.menu.label, and thousands of theme-specific keys defined in section schemas via the t filter in settings.

When a merchant publishes a language in the admin, Shopify merges theme locale files with translations edited in the Translate & Adapt app or the admin language editor. Liquid does not hardcode English strings in production themes; it references keys with translation filters so copy updates do not require code deploys.

Developers must generate complete locale keys for every user-visible string in sections, snippets, and config/settings_schema.json. Missing keys fall back to English or show raw key paths in the theme editor preview, which breaks trust for non-English markets.

The t filter translates a key from locale files: {{ 'products.product.add_to_cart' | t }}. Pass variables for interpolation: {{ 'cart.summary.item_count' | t: count: cart.item_count }}. In section schemas, use "label": "t:sections.featured_collection.settings.title.label" so settings labels localize automatically.

For dynamic content that merchants control (product titles, collection descriptions), Shopify uses translatable resources in admin, not theme locale files. Theme Liquid outputs {{ product.title }} and Shopify serves the correct language version when the customer selects a locale on a multilingual store.

Pluralization and gender rules vary by language. Use JSON locale structure with plural keys where Shopify supports them, or split keys (_one, _other) per documentation. Test Hindi, Arabic, and French layouts: string length changes break narrow buttons; RTL languages require dir="rtl" on html and mirrored CSS utilities in theme.css.

Markets and Shopify Payments enable selling in multiple currencies. The theme displays money with the money filter and currency codes appropriate to the customer's market: {{ price | money_with_currency }}. cart.currency and localization.available_countries inform country/currency selectors rendered in the header or footer.

Do not confuse display currency with settlement. Shopify converts at checkout per market rules; themes should not hand-roll exchange rates in Liquid. Use country/region selector snippets provided by Shopify patterns or Dawn-derived implementations, and ensure AJAX cart endpoints return updated money strings after switching market context.

For fixed-price merchandising (₹999 sticker regardless of FX), merchants use manual price lists per market in admin; themes read variant.price in the active market without custom math. Document for merchants when to use automatic conversion versus localized price lists.

Shopify Markets groups countries, domains, subfolders, and catalogs. Themes branch content with localization.market, country filters, and alternate URLs in hreflang meta tags. A .com store might serve /en-in/ for India and /fr-fr/ for France; theme links must use routes within the active market rather than hardcoded /collections/all paths that ignore subfolder prefixes.

Market-specific merchandising uses metafields, metaobjects, or duplicate sections with visibility rules in the theme editor (if supported) and conditional Liquid: {% if localization.country.iso_code == 'IN' %}. Prefer admin-driven metaobjects for hero swaps per market so marketers control content without deploys.

SEO requires localized canonical URLs, translated meta descriptions from resources, and sitemap entries per domain. Theme developers coordinate with SEO apps and ensure structured data (JSON-LD) uses translated product fields and correct currency in offers.

Start new themes with en.default.json keys for every string. Add target languages by copying the default file structure. Run Theme Check for missing translations. Preview with ?locale=hi in the theme editor and test checkout in each published market.

QA: switch language on mobile, verify cart drawer strings, confirm selling plan and subscription labels, test empty states and error messages, and validate that form placeholders in customer login/register localize. Performance: additional locale JSON increases theme zip size slightly; avoid duplicating large HTML blocks per language—use t keys instead.

Teams selling across India and export markets benefit from separating operational copy (COD messaging, GST notes) into locale keys merchants can edit, while ADSPOC engineers wire Markets, payments, and shipping apps once in the architecture layer.