Setup multilingual and multi-regional storefronts with URL paths
In this guide you will learn how to setup your Hydrogen project for supporting multi-region and multilingual storefronts by using URL paths.
For example, say you have a storefront that should work in English (EN) and in non-regional French (FR) for different customers.
You will setup the project to handle requests as following:
RequirementsAnchor link to section titled "Requirements"
Step 1: Create a utility that checks the requested URL paths localeAnchor link to section titled "Step 1: Create a utility that checks the requested URL paths locale"
The following is an example utility function with the following locales
Step 2: Match routes that contain language in the URLAnchor link to section titled "Step 2: Match routes that contain language in the URL"
Using Remix's optional segments, add
($locale) in front of your routes.
This ensures that routes such as
/fr/products/123 matches to the same product route file in Remix, so that the correct page is rendered.
The following is an example of files and folders before file rename with
After renaming the routes with
($locale), your new file structure should look like the following example:
At this point, you should see your pages render when you make requests to
/fr/ URL paths.
Step 3: Add i18n to the storefront clientAnchor link to section titled "Step 3: Add i18n to the storefront client"
i18n to the result of the utility function when creating the Hydrogen storefront client.
By doing this, you now have the locale available throughout the app for every storefront query.
Step 4: Add @inContext directive to your GraphQL queriesAnchor link to section titled "Step 4: Add @inContext directive to your GraphQL queries"
To support international pricing and languages in Storefront API, you need to pass the
$language with an
@inContext directive within any requests.
Update your GraphQL queries with
inContext directives to include
$language. Hydrogen automatically injects these parameters.
For example, this is a Storefront API query that returns featured collections from the homepage. This updates it to include the
You don't need to manually provide query variables for
language. You can make the query with
storefront.query in the data loader and see the right language and currencies for each request.
Hydrogen automatically injects the locale parameters to
storefront.query based on what was defined in
i18n when you created the client.
For example, if a request came from
hydrogen.fr, then the country
CA and language
FR are used as defined in the utilities function.
The Storefront API returns the correct currency and language if the store was set up in the Shopify admin.
If you want to override the locale determined by your utility option, then you can supply the query variables to the
Step 5: Match non-existent pagesAnchor link to section titled "Step 5: Match non-existent pages"
A request to
/this-route-does-not-exist should return a
404 not found page.
To achieve this, create a
$.(tsx|jsx) file in the
/app/routes/` folder. This Remix splat route will handle all the non-matching routes.
Step 6: Handle invalid URL lang parametersAnchor link to section titled "Step 6: Handle invalid URL lang parameters"
/app/routes/index.jsx, set up handling of invalid URL parameters localization. For example, any request with lang parameter
au when you don't handle this language, should return a
Step 7: Create a utility function to add a language path prefixAnchor link to section titled "Step 7: Create a utility function to add a language path prefix"
Create a utility function that adds the locale path prefix to any URL path. For example, if the path is
/products and the buyer prefers the locale
fr_CA, then the utility function converts it to
Use this utility function anywhere you need to define a localized path. For example, form actions should have the localized path.
Step 8: Create Link component with locale path prefixAnchor link to section titled "Step 8: Create Link component with locale path prefix"
<Link /> wrapper component that adds the locale path prefix. You can create this file in any components folder. In the case of the Hydrogen demo store,
components folder was created for base components.
Step 9: Make sure redirects are properly url encodedAnchor link to section titled "Step 9: Make sure redirects are properly url encoded"
If you have multilingual handles for your product or collection, for example,
products/スノーボード, make sure to encode url when making redirects.
- Create a country selector: Learn how to setup a country selector to allow users to choose their own country.