Internationalization in a Headless Storefront

Selling internationally requires internationalization — supporting multiple languages, currencies, regions, and localised experiences (as the Markets and international-SEO discussions cover) — and on a headless storefront, you’re responsible for building much of this internationalization yourself, in your custom front-end. On a standard Shopify theme, Shopify Markets (as that discussion covers) handles much internationalization (currency, language, localised experiences, structure, hreflang) with theme support, whereas in headless your custom front-end must implement the internationalization (localised content, currency/language handling, region routing, international SEO), typically drawing on Shopify’s internationalization capabilities (Markets, the Storefront API’s internationalization support) but building the front-end internationalization yourself. This gives you control over the international experience but also the responsibility (and complexity) of building it. For headless stores selling internationally, understanding what internationalization involves and how to do it well is important. This piece covers internationalization in a headless storefront: what it involves, what you’re responsible for, how to do it, and how to do it well. (This connects to the Markets and international-SEO discussions; this focuses on internationalization in headless. Note: this is technical; specifics evolve — this covers the general picture.)

This piece covers what internationalization involves, what you’re responsible for in headless (versus a theme), how to implement it, and how to do it well. Because headless makes internationalization your responsibility to build, and doing it well matters for international selling. Let me walk through it.

What internationalization involves

Internationalization (for a headless storefront selling internationally) involves supporting the international aspects customers expect. Multiple languages — supporting multiple languages (translated content, the store in the customer’s language, as the Markets and translation discussions cover) — a core internationalization aspect (language localisation). Multiple currencies — supporting multiple currencies (showing and handling prices in the customer’s currency, as the Markets discussion covers) — currency localisation. Region/market handling — handling different regions/markets (region-appropriate content, pricing, availability, as the Markets discussion covers), so each region gets its appropriate experience — region handling. Localised experiences — providing localised experiences (language, currency, region-relevant content, local payment methods, duties/taxes handling, as the Markets discussion covers), so international customers get a properly localised experience (versus a generic one) — localisation (the goal). Region routing/detection — routing or directing users to the appropriate regional/language version (via detection, selection, or URL structure, as the international-SEO discussion covers), so users reach the right version — region routing. International SEO — international SEO (hreflang, URL structure, correct targeting, as the international-SEO discussion covers), so the right versions rank for the right regions/languages — international SEO (a key aspect). International checkout — the international checkout (currency, local payment methods, duties/taxes, as the Markets and checkout discussions cover), typically on Shopify’s checkout (which handles much international checkout, as the keeping-checkout discussion covers) — international checkout. And a coherent international experience — bringing these together into a coherent international experience (language, currency, region, localisation, routing, SEO, checkout working together per region) — the overall international experience. So internationalization involves supporting multiple languages (translated content), multiple currencies, region/market handling, localised experiences (language, currency, region-relevant content, payment methods, duties/taxes), region routing/detection, international SEO (hreflang, structure), and international checkout — brought together into a coherent international experience per region. So internationalization is the set of capabilities for selling internationally with properly localised experiences per region/language. The next section covers what you’re responsible for in headless. So internationalization involves languages, currencies, regions, localisation, routing, international SEO, and checkout — a coherent localised international experience.

What you’re responsible for in headless (versus a theme)

In headless, you’re responsible for building much internationalization that Shopify Markets handles with theme support. Theme + Markets handles much — on a standard theme, Shopify Markets (as that discussion covers) handles much internationalization (currency, language, localised pricing, region structure, hreflang) with theme support, so a theme + Markets provides much internationalization relatively straightforwardly — theme + Markets (handles much). Headless: you build the front-end internationalization — in headless, your custom front-end handles the storefront experience, so you build the front-end internationalization (localised content display, currency/language handling and switching, region routing, international SEO in the front-end), drawing on Shopify’s internationalization data/capabilities but implementing the front-end yourself — your responsibility (build the front-end internationalization). Localised content display — you’re responsible for displaying localised content (the right language content, currency, region-relevant content per region/language) in your front-end, fetching and rendering the appropriate localised content (from Shopify/Markets and/or a CMS, as the headless-CMS and Markets discussions cover) — localised content (yours to implement). Currency and language handling — you’re responsible for handling currency and language in the front-end (showing the right currency and language, switching, as the Markets discussion covers), implementing the currency/language logic in your front-end — currency/language (yours). Region routing and detection — you’re responsible for region routing/detection (directing users to the right regional/language version, via URL structure, detection, or selection, as the international-SEO discussion covers) in your front-end — region routing (yours). International SEO in the front-end — you’re responsible for implementing international SEO in your front-end (hreflang, URL structure, correct targeting, as the international-SEO and headless-SEO discussions cover), since headless SEO (including international) is your responsibility (as the headless-SEO discussion covers) — international SEO (yours, and important). Drawing on Shopify’s internationalization — you draw on Shopify’s internationalization capabilities (Markets’ data and configuration, the Storefront API’s internationalization support — currency, language, market data, as the Storefront-API and Markets discussions cover) to get the internationalization data, then implement the front-end using it — leveraging Shopify’s internationalization data (while building the front-end). Checkout stays on Shopify (international) — the international checkout typically stays on Shopify (which handles international checkout — currency, payment methods, duties/taxes, as the keeping-checkout and Markets discussions cover), so you don’t build international checkout (Shopify handles it, as with checkout generally) — international checkout (Shopify’s, a relief). And more responsibility and complexity — overall, headless internationalization is more responsibility and complexity (building the front-end internationalization) than a theme + Markets (which handles much) — so it’s more work in headless (the trade-off for control) — more responsibility. So in headless, you’re responsible for building the front-end internationalization: localised content display, currency and language handling, region routing/detection, and international SEO in the front-end — drawing on Shopify’s internationalization capabilities (Markets, Storefront API) for the data, while the international checkout typically stays on Shopify (a relief) — more responsibility and complexity than a theme + Markets. So in headless you build the front-end internationalization (content, currency/language, routing, SEO), drawing on Shopify’s data, with checkout on Shopify. The next section covers implementing it. So in headless you’re responsible for building the front-end internationalization (localised content, currency/language, routing, international SEO), drawing on Shopify’s capabilities, with checkout staying on Shopify.

How to implement internationalization in headless

Implementing internationalization in a headless storefront involves building it in your front-end, leveraging Shopify’s capabilities and good practices (developer work, at an overview level). Use Shopify’s internationalization capabilities — draw on Shopify Markets and the Storefront API’s internationalization support (as those discussions cover) for the internationalization data (currency, language, market configuration, localised content), so you build the front-end on Shopify’s internationalization foundation (versus reinventing it) — leveraging Shopify’s capabilities (the foundation). Fetch and display localised content — implement fetching and displaying localised content (the right language, currency, region-relevant content per region/language) in your front-end (from Shopify/Markets and/or a headless CMS for content, as the headless-CMS discussion covers) — localised content display. Implement currency and language handling — implement currency and language handling/switching in your front-end (showing the right currency and language, letting users switch or detecting appropriately, using Shopify’s currency/language data) — currency/language handling. Implement region routing — implement region routing (directing users to the right regional/language version — via URL structure, detection, or a selector, as the international-SEO discussion covers), so users reach and can access the right version — region routing. Implement international SEO — implement international SEO in your front-end (hreflang annotations, correct URL structure, correct targeting, as the international-SEO and headless-SEO discussions cover), since it’s your responsibility in headless and important for international ranking — international SEO (get it right). Use i18n libraries/framework support — use internationalization (i18n) libraries and your framework’s internationalization support (frameworks like Next.js have i18n features/routing, and i18n libraries handle translations and localisation), so you leverage tools for internationalization (versus building it all from scratch) — i18n tools (a help). Keep checkout on Shopify — keep the international checkout on Shopify (handling currency, payment methods, duties/taxes internationally, as the keeping-checkout and Markets discussions cover), so you leverage Shopify’s international checkout (not building it) — Shopify’s checkout (a relief). Handle it with the rendering/caching — implement internationalization within your rendering and caching approach (as the caching/ISR discussion covers — serving the right localised, cached versions per region/language), so localised content is served efficiently and correctly — integration with rendering/caching. Test per region/language — test the internationalization per region and language (the right content, currency, language, routing, SEO, and checkout for each), since internationalization is complex and error-prone (verify each region works) — testing (important). And use the right expertise — use developers with internationalization and headless expertise (as the headless-team discussion covers), given internationalization’s complexity in headless (building the front-end internationalization correctly) — expertise (needed for correct international headless). So implement internationalization in headless by drawing on Shopify’s internationalization capabilities (Markets, Storefront API) for the data, implementing localised content display, currency and language handling, region routing, and international SEO in your front-end, using i18n libraries and framework support (leveraging tools), keeping the international checkout on Shopify, integrating with your rendering/caching, testing per region/language, and using the right expertise. The keys are leveraging Shopify’s internationalization capabilities and i18n tools/framework support (versus building from scratch), implementing the front-end internationalization (content, currency/language, routing, SEO) correctly, keeping checkout on Shopify, and testing per region. So implement headless internationalization by building the front-end (content, currency/language, routing, SEO) on Shopify’s capabilities and i18n tools, with checkout on Shopify, tested per region. The next section covers doing it well. So implement headless internationalization by leveraging Shopify’s capabilities and i18n tools to build the front-end internationalization (content, currency/language, routing, SEO), with checkout on Shopify, tested per region.

How to do it well

Doing internationalization well in a headless storefront means building a good localised international experience with the right approach and expertise. Leverage Shopify’s capabilities and tools — leverage Shopify’s internationalization capabilities (Markets, Storefront API) and i18n libraries/framework support (as covered), so you build on solid foundations and tools (versus reinventing internationalization) — the smart approach (leverage, don’t rebuild). Build well localised experiences — build well localised experiences (proper translation, right currency, region-relevant content and localisation, as the Markets and translation discussions cover), since good localisation drives international conversion and experience (versus superficial or poor localisation) — quality localisation (not just currency conversion). Get international SEO right — get the international SEO right (hreflang, structure, targeting, as the international-SEO and headless-SEO discussions cover), since it’s your responsibility in headless and critical for international ranking (and headless SEO done wrong is a pitfall, as the headless-SEO discussion covers) — correct international SEO (important). Keep checkout on Shopify — keep the international checkout on Shopify (handling international payments, duties/taxes, as the keeping-checkout discussion covers), leveraging Shopify’s international checkout (avoiding building it) — Shopify’s checkout (leverage it). Ensure a coherent per-region experience — ensure a coherent, correct experience per region/language (the right content, currency, language, routing, SEO, and checkout working together for each region), so international customers get a proper localised experience — coherent localisation. Test and verify per region — test and verify the internationalization per region/language thoroughly (each region’s experience, SEO, and checkout working), since it’s complex and error-prone (as the international-SEO discussion covers for SEO) — thorough testing (per region). Use the right expertise — use developers with internationalization and headless expertise (as the headless-team discussion covers), since building headless internationalization well requires the expertise — expertise (key). Consider the complexity in the headless decision — factor the internationalization complexity into your headless decision (as the is-headless-worth-it discussion covers): if you sell internationally, building headless internationalization is added complexity/responsibility (versus a theme + Markets), so weigh it (it’s part of headless’s cost for international stores) — decision consideration. And maintain it — maintain the internationalization ongoing (as you add content, regions, or languages, ensuring they’re localised and correct, as the maintenance discussion covers) — ongoing maintenance. So do internationalization well in headless by leveraging Shopify’s capabilities and i18n tools (building on foundations, not reinventing), building well localised experiences (quality localisation, not just currency conversion), getting international SEO right (critical, and your responsibility), keeping checkout on Shopify (leveraging its international checkout), ensuring a coherent correct per-region experience, testing and verifying per region thoroughly, using the right expertise, factoring the complexity into the headless decision, and maintaining it. The keys are leveraging Shopify’s capabilities and tools, building quality localised experiences, getting international SEO right, keeping checkout on Shopify, and testing per region with the right expertise. So do headless internationalization well by leveraging Shopify’s capabilities and tools, building quality localised experiences with correct international SEO, keeping checkout on Shopify, and testing per region. So do headless internationalization well by leveraging Shopify’s capabilities and i18n tools, building quality localised experiences with correct international SEO and Shopify’s checkout, tested per region, with the right expertise.

The bottom line

Selling internationally requires internationalization — supporting multiple languages, currencies, regions, and localised experiences — and on a headless storefront, you’re responsible for building much of this internationalization yourself in your custom front-end. Internationalization involves supporting multiple languages (translated content), multiple currencies, region/market handling, localised experiences (language, currency, region-relevant content, local payment methods, duties/taxes), region routing and detection (directing users to the right version), international SEO (hreflang, URL structure, correct targeting), and international checkout — brought together into a coherent, properly localised international experience per region. On a standard Shopify theme, Shopify Markets handles much of this (currency, language, localised pricing, region structure, hreflang) with theme support, relatively straightforwardly. But in headless, your custom front-end handles the storefront experience, so you’re responsible for building the front-end internationalization: displaying localised content (the right language, currency, region-relevant content), handling currency and language (and switching), region routing and detection, and international SEO in the front-end — drawing on Shopify’s internationalization capabilities (Markets’ data and configuration, the Storefront API’s internationalization support) for the data, while the international checkout typically stays on Shopify (which handles international currency, payment methods, and duties/taxes — a relief). This gives you control over the international experience but more responsibility and complexity than a theme plus Markets. Implement it by drawing on Shopify’s internationalization capabilities (the foundation), implementing localised content display, currency and language handling, region routing, and international SEO in your front-end, using internationalization (i18n) libraries and your framework’s i18n support (leveraging tools rather than building from scratch), keeping the international checkout on Shopify, integrating internationalization with your rendering and caching (serving the right localised versions efficiently), testing per region and language (since it’s complex and error-prone), and using developers with internationalization and headless expertise. Do it well by leveraging Shopify’s capabilities and i18n tools (building on foundations, not reinventing internationalization), building well localised experiences (proper translation, right currency, region-relevant content — quality localisation, not just currency conversion, since good localisation drives international conversion), getting the international SEO right (critical and your responsibility in headless, since headless SEO done wrong is a pitfall), keeping the international checkout on Shopify (leveraging its international checkout), ensuring a coherent, correct experience per region and language, testing and verifying per region thoroughly, using the right expertise, factoring the internationalization complexity into your headless decision (it’s added complexity and responsibility for international stores versus a theme plus Markets), and maintaining it ongoing. The keys are leveraging Shopify’s internationalization capabilities and i18n tools, building quality localised experiences, getting international SEO right, keeping checkout on Shopify, and testing per region with the right expertise. So for a headless store selling internationally, understand that internationalization becomes your responsibility to build in the front-end (versus Shopify Markets handling much on a theme) — a real added complexity and responsibility — and do it well by leveraging Shopify’s capabilities and i18n tools, building quality localised experiences with correct international SEO, keeping checkout on Shopify, and testing thoroughly per region. Done well, headless internationalization delivers the coherent, properly localised international experiences that international selling requires, with the control headless provides; done poorly, it undermines your international experience and SEO — so getting it right (with the right expertise, leveraging Shopify’s foundations) is important for headless international selling.

Frequently asked questions

What does internationalization involve for a headless storefront?

It involves supporting all the aspects of selling internationally with properly localised experiences per region and language. That includes multiple languages (translated content, the store in the customer’s language), multiple currencies (showing and handling prices in the customer’s currency), region and market handling (region-appropriate content, pricing, and availability), localised experiences (language, currency, region-relevant content, local payment methods, and duties/taxes handling), region routing and detection (directing users to the appropriate regional or language version), international SEO (hreflang, URL structure, and correct targeting so the right versions rank for the right regions and languages), and international checkout (currency, local payment methods, duties/taxes). These come together into a coherent, properly localised international experience for each region. On a headless storefront, you’re responsible for building much of this in your custom front-end (versus a theme, where Shopify Markets handles much of it), drawing on Shopify’s internationalization capabilities for the underlying data while implementing the front-end experience yourself — though the international checkout typically stays on Shopify.

What am I responsible for building in headless internationalization?

The front-end internationalization that Shopify Markets handles with theme support on a standard theme. Specifically, you’re responsible for displaying localised content in your front-end (the right language, currency, and region-relevant content per region), handling currency and language (showing the right ones and enabling switching or detection), region routing and detection (directing users to the correct regional or language version via URL structure, detection, or a selector), and implementing international SEO in your front-end (hreflang, correct URL structure, and targeting — which is your responsibility in headless and important for international ranking). You draw on Shopify’s internationalization capabilities (Markets’ data and configuration, and the Storefront API’s internationalization support) to get the currency, language, and market data, then implement the front-end experience using it. The good news is the international checkout typically stays on Shopify, which handles international currency, payment methods, and duties/taxes — so you don’t build that. Overall, it’s more responsibility and complexity than a theme plus Markets, which is the trade-off for headless’s control over the international experience.

How do I implement internationalization in a headless build?

Build the front-end internationalization on Shopify’s foundations, leveraging tools. Draw on Shopify Markets and the Storefront API’s internationalization support for the data (currency, language, market configuration, localised content), then implement in your front-end: fetching and displaying localised content (the right language, currency, and region-relevant content, from Shopify/Markets and/or a headless CMS), currency and language handling and switching, region routing and detection, and international SEO (hreflang, correct URL structure, and targeting). Use internationalization (i18n) libraries and your framework’s i18n support (frameworks like Next.js have internationalization features and routing) rather than building it all from scratch. Keep the international checkout on Shopify (leveraging its handling of international currency, payment methods, and duties/taxes). Integrate internationalization with your rendering and caching so the right localised versions are served efficiently, test thoroughly per region and language (since it’s complex and error-prone), and use developers with internationalization and headless expertise. The keys are leveraging Shopify’s capabilities and i18n tools, implementing the front-end internationalization correctly, keeping checkout on Shopify, and testing per region.

How do I do headless internationalization well?

Leverage foundations and tools, build quality localised experiences, and get the SEO right. Leverage Shopify’s internationalization capabilities (Markets, Storefront API) and i18n libraries and framework support, building on solid foundations rather than reinventing internationalization. Build well localised experiences — proper translation (not just machine translation), the right currency, and region-relevant content and localisation — since good localisation, not just currency conversion, is what drives international conversion and experience. Get the international SEO right (hreflang, URL structure, correct targeting), since it’s your responsibility in headless and critical for international ranking, and headless SEO done wrong is a known pitfall. Keep the international checkout on Shopify to leverage its international-checkout handling. Ensure a coherent, correct experience per region and language (content, currency, language, routing, SEO, and checkout working together), test and verify thoroughly per region (it’s complex and error-prone), and use developers with the right internationalization and headless expertise. Also factor the internationalization complexity into your headless decision, since for international stores it’s real added complexity and responsibility versus a theme plus Markets. And maintain it as you add content, regions, or languages.