Internationalization with Shopify Markets
Anchor to IntroductionIntroduction
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 React Router to set up internationalization (i18n) that leverages a merchant’s market configuration. It also makes locales available throughout the app and in Storefront API queries.
Anchor to RequirementsRequirements
- 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.
Anchor to Setup the default localeSetup 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.
Anchor to Setup a multi-region and multilingual storefrontSetup 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.
Learn how to support multiple countries and languages by using URL paths
Learn how to support multiple countries and languages by using domains and subdomains
Anchor to Create a country selectorCreate 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.
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.
Anchor to Developer tools and resourcesDeveloper tools and resources
Anchor to Next stepsNext steps
- 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