Internationalization helps merchants expand their business to a global audience by creating shopping experiences in local languages and currencies. This guide provides information on configuring localized experiences for merchants and customers in your Hydrogen storefront.
LocalizationAnchor link to section titled "Localization"
Shopify helps merchants all over the world, sell to customers all over the world. This means that there are multiple currencies and languages that they might need to sell in.
Hydrogen includes the following components and hooks for localization:
useLocalization: A hook that returns the locale, country, and language of the current page.
Default configurationAnchor link to section titled "Default configuration"
You can configure your Hydrogen storefront's default language and country by setting the
defaultCountryCode properties in the Hydrogen configuration file.
ShopifyProvider uses these default values, unless it's passed an override from the
In the following example, the default language is set to English and the default country is set to the United States:
Overriding the default localeAnchor link to section titled "Overriding the default locale"
You can change the active country and language at runtime by passing the
languageCode props to the
Retrieving translated content from the Storefront APIAnchor link to section titled "Retrieving translated content from the Storefront API"
You can use the
useLocalization hook to pass the visitor's active
language into your Storefront API query. For example, you might need to create a product page in a customer's language:
For more information about retrieving language translations and the
@inContext directive, refer to the Storefront API documentation.
Search engine optimization (SEO)Anchor link to section titled "Search engine optimization (SEO)"
For more information about customizing the output of SEO-related tags in your Hydrogen app, refer to SEO.
International routingAnchor link to section titled "International routing"
Hydrogen supports domains and subfolders for internationalized routes.
- Top-level domain routes:
- Subdomain routes:
- Subfolder routes:
Set up domains and subdomainsAnchor link to section titled "Set up domains and subdomains"
To set up domains and subdomains, complete the following steps:
From your Shopify admin, under Settings > Domains, update your domains and subdomains to target your custom storefront. Your primary domain is used for the default URL when customers visit your store.
For non-primary domains and subdomains where you want to host a localized experience, set the domain type to Routing.
Set up subfoldersAnchor link to section titled "Set up subfolders"
Subfolder routes use the visitor's locale in the URL path. In Hydrogen, you can use the
FileRoutes component to prefix all file routes with a locale using the
basePath parameter, and to source the corresponding file routes:
After you've set up your routing strategies, you can create redirects based on your visitor's locale. You can trigger redirects manually. For example, a visitor changes their country using a dropdown menu, or automatically, based on a visitor's geolocation.
Shopify recommends manual redirects for customer privacy and SEO best practices. For example, reference the
CountrySelector.client component in the Hydrogen demo store.
If you're hosting your Hydrogen storefront on Oxygen, then you can access a visitor’s geolocation by using the
request object and retrieve it using
View a full list of custom HTTP headers available from Oxygen.
If you're hosting your Hydrogen storefront on a platform that isn't Oxygen, then you can access the Accept-Language HTTP header as a hint to the visitor's country and language preference: