Internationalization with Shopify Markets
Introduction
Anchor link to section titled "Introduction"Shopify Markets helps merchants expand their business to a global audience by creating shopping experiences in local languages and currencies.
Hydrogen provides patterns on top of Remix to setup internationalization (i18n) that leverages a merchant’s market configuration. It also makes locales available throughout the app and in Storefront API queries.
Requirements
Anchor link to section titled "Requirements"- You've completed the Hydrogen Getting Started with a
Hello Worldexample project. - You've setup you store's regions and languages using Shopify Markets.
- You're familiar with using the Storefront API with Shopify Markets.
Setup the default locale
Anchor link to section titled "Setup the default locale"Before setting up your Hydrogen Storefront, make sure to set a default language and country code. This ensures that the correct language and currency are used throughout the app.
This guide shows you how to add or update your custom storefront's default language.
Setup a multi-region and multilingual storefront
Anchor link to section titled "Setup a multi-region and multilingual storefront"Shopify recommends that storefronts with multiple regions and languages have separate URLs for each locale. This improves accessibility for search engines and screen readers.
Use one of the following methods to create different URLs for each region and language.
| Option | URL examples |
|---|---|
| Localization scheme using URL paths | hydrogen.shop/fr, hydrogen.shop/es |
| Localization scheme using domains and subdomains | hydrogen.fr, hydrogen.es |
The advantage of using the URL paths method is that you only need to set this up from the app and you don't need to setup any domain infrastructure.
Create a country selector
Anchor link to section titled "Create a country selector"Users will want to switch your Storefront to their preferred country. It is good user experience to provide a way for them to achieve this within your store.
Localization detection using headers, cookies, or URL search params
Anchor link to section titled "Localization detection using headers, cookies, or URL search params"While it's possible to detect an approximation of the user's locale by reading the header, cookies or URL search params. Shopify only recommends this to improve the experience of the user.
A good example of detecting localization is to show a banner to asking the user if they want to switch country.
A bad example of localization detection is when the user gets automatically redirected.
Other drawbacks of this approach are that page caching ignores locale cookies, headers and URL search params. SEO bots tend to origin from the US, don't have cookies and will not change their accept-language headers.
Developer tools and resources
Anchor link to section titled "Developer tools and resources"- Learn how to set up default locale for your storefront.
- Learn how to set up multiregion and multilingual storefront with URL paths to get the right language and currency.
- Learn how to set up multiregion and multilingual storefront with domains and subdomains to get the right language and currency.
- Learn how to create a country selector to allow users to choose their own country.
- Learn how to set up locale detection using response header, cookies, or URL search params.
- Learn how to set up localization detection using headers, cookies or URL search params