Setup multilingual and multi-regional storefronts with URL paths
This guide might not be compatible with features introduced in Hydrogen version 2025-05 and above. Check the latest documentation if you encounter any issues.
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:
Language | URL path |
---|---|
English | ca.hydrogen.shop |
French | ca.hydrogen.shop/fr |
Anchor to RequirementsRequirements
- You have a working Hydrogen project. For more information, refer to the getting started guide.
- You have setup the regions and languages you chose for your store with Shopify Markets.
- You're familiar with using the Storefront API with Shopify Markets.
Anchor to Step 1: Create a utility that checks the requested URL paths localeStep 1: Create a utility that checks the requested URL paths locale
Create a utility function that reads the requested host and directory path which return the right Locale
object using the Storefronts API's supported language and country codes.
You can use the /app/lib/utils.js
in the Hydrogen demo store as a reference.
The following is an example utility function with the following locales en_CA
, fr_CA
and en_US
.
utils
/app/lib/utils.js
export function getLocaleFromRequest(request) {
// Get the user request URL
const url = new URL(request.url);
// Match the URL host
switch (url.host) {
case 'ca.hydrogen.shop':
// This regex matches `/fr/` paths in the request
if (/^\/fr($|\/)/.test(url.pathname)) {
return {
language: 'FR',
country: 'CA',
};
} else {
return {
language: 'EN',
country: 'CA',
};
}
break;
default:
return {
language: 'EN',
country: 'US',
};
}
}
export function getLocaleFromRequest(request: Request): Locale {
// Get the user request URL
const url = new URL(request.url);
// Match the URL host
switch (url.host) {
case 'ca.hydrogen.shop':
// This regex matches `/fr/` paths in the request
if (/^\/fr($|\/)/.test(url.pathname)) {
return {
language: 'FR',
country: 'CA',
};
} else {
return {
language: 'EN',
country: 'CA',
};
}
break;
default:
return {
language: 'EN',
country: 'US',
};
}
}
The Locale
object returned should resemble the following example, which is using the Storefont API's supported language and country codes.
TypeScript
Anchor to Step 2: Match routes that contain language in the URLStep 2: Match routes that contain language in the URL
Using React Router's optional segments, add ($locale)
in front of your routes.
This ensures that routes such as /products/123
and /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 ($locale)
:
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.
Anchor to Step 3: Add i18n to the storefront clientStep 3: Add i18n to the storefront client
In your server.js
, update 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.
/server.js
const {storefront} = createStorefrontClient({
...
i18n: getLocaleFromRequest(request),
...
});
const {storefront} = createStorefrontClient({
...
i18n: getLocaleFromRequest(request),
...
});
Anchor to Step 4: Add @inContext directive to your GraphQL queriesStep 4: Add @in Context directive to your Graph QL queries
To support international pricing and languages in Storefront API, you need to pass the $country
and $language
with an @inContext
directive within any requests.
Update your GraphQL queries with inContext
directives to include $country
and $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 inContext
directive.
GraphQL queries
Before
After
You don't need to manually provide query variables for country
and language
. You can make the query with storefront.query
in the data loader and see the right language and currencies for each request.
export async function loader({
context: {storefront},
}) {
return json({
featureCollections: await storefront.query<{
collections;
}>(FEATURED_COLLECTIONS_QUERY),
});
}
export async function loader({
context: {storefront},
}: LoaderArgs) {
return json({
featureCollections: await storefront.query<{
collections: CollectionConnection;
}>(FEATURED_COLLECTIONS_QUERY),
});
}
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 storefront.query
:
export async function loader({
context: {storefront},
}) {
return json({
featureCollection: await storefront.query(FEATURED_COLLECTIONS_QUERY, {
variables: {
country: 'CA', // Always query back in CA currency
language: 'FR', // Always query back in FR language
}
}),
});
}
export async function loader({
context: {storefront},
}: LoaderArgs) {
return json({
featureCollection: await storefront.query<{
collections: CollectionConnection;
}>(FEATURED_COLLECTIONS_QUERY, {
variables: {
country: 'CA', // Always query back in CA currency
language: 'FR', // Always query back in FR language
}
}),
});
}
Anchor to Step 5: Match non-existent pagesStep 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.
Catch-all route
/app/routes/$.jsx
export async function loader() {
throw new Response('Not found', {status: 404});
}
export default function Component() {
return null;
}
export async function loader() {
throw new Response('Not found', {status: 404});
}
export default function Component() {
return null;
}
Anchor to Step 6: Handle invalid URL lang parametersStep 6: Handle invalid URL lang parameters
In the /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 404
.
Index route
/app/routes/index.jsx
export async function loader({
request,
params,
context,
}) {
const {language, country} = context.storefront.i18n;
if (
params.locale &&
params.locale.toLowerCase() !== `${'{'}language{'}'}-${'{'}country{'}'}`.toLowerCase()
) {
// If the locale URL param is defined, yet we still are on `EN-US`
// the the locale param must be invalid, send to the 404 page
throw new Response(null, {status: 404});
}
...
}
export async function loader({
request,
params,
context,
}: LoaderArgs) {
const {language, country} = context.storefront.i18n;
if (
params.locale &&
params.locale.toLowerCase() !== `${'{'}language{'}'}-${'{'}country{'}'}`.toLowerCase()
) {
// If the locale URL param is defined, yet we still are on `EN-US`
// the the locale param must be invalid, send to the 404 page
throw new Response(null, {status: 404});
}
...
}
Anchor to Step 7: Create a utility function to add a language path prefixStep 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 /fr/products
.
Use this utility function anywhere you need to define a localized path. For example, form actions should have the localized path.
utils
/server.js
export function usePrefixPathWithLocale(path) {
const [root] = useMatches();
const selectedLocale = root.data.selectedLocale;
return selectedLocale
? `${selectedLocale.pathPrefix}${
path.startsWith('/') ? path : '/' + path
}`
: path;
}
export function usePrefixPathWithLocale(path: string) {
const [root] = useMatches();
const selectedLocale = root.data.selectedLocale;
return selectedLocale
? `${selectedLocale.pathPrefix}${
path.startsWith('/') ? path : '/' + path
}`
: path;
}
Anchor to Step 8: Create Link component with locale path prefixStep 8: Create Link component with locale path prefix
Create a <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.
Make sure your project is using this Link
component for all inbound navigation. This ensures the prefix locale gets appended for every link. For example navigating from fr/products
to fr/collections
without this Link
component loses the fr
path.
Link
/app/components/Link.js
import {
Link as RemixLink,
NavLink as RemixNavLink,
useMatches,
} from '@remix-run/react';
import {usePrefixPathWithLocale} from '~/lib/utils';
export function Link(props) {
const {to, className, ...resOfProps} = props;
const [root] = useMatches();
const selectedLocale = root.data.selectedLocale;
let toWithLocale = to;
if (typeof to === 'string') {
toWithLocale = selectedLocale ? `${selectedLocale.pathPrefix}${'{'}to{'}'}` : to;
}
if (typeof className === 'function') {
return (
<RemixNavLink
to={toWithLocale}
className={className}
{...resOfProps}
/>
);
}
return (
<RemixLink to={toWithLocale} className={className} {...resOfProps} />
);
}
export function usePrefixPathWithLocale(path) {
const [root] = useMatches();
const selectedLocale = root.data.selectedLocale;
return selectedLocale
? `${selectedLocale.pathPrefix}${
path.startsWith('/') ? path : '/' + path
}`
: path;
}
import {
Link as RemixLink,
NavLink as RemixNavLink,
useMatches,
} from '@remix-run/react';
import {usePrefixPathWithLocale} from '~/lib/utils';
export function Link(props) {
const {to, className, ...resOfProps} = props;
const [root] = useMatches();
const selectedLocale = root.data.selectedLocale;
let toWithLocale = to;
if (typeof to === 'string') {
toWithLocale = selectedLocale ? `${selectedLocale.pathPrefix}${'{'}to{'}'}` : to;
}
if (typeof className === 'function') {
return (
<RemixNavLink
to={toWithLocale}
className={className}
{...resOfProps}
/>
);
}
return (
<RemixLink to={toWithLocale} className={className} {...resOfProps} />
);
}
export function usePrefixPathWithLocale(path: string) {
const [root] = useMatches();
const selectedLocale = root.data.selectedLocale;
return selectedLocale
? `${selectedLocale.pathPrefix}${
path.startsWith('/') ? path : '/' + path
}`
: path;
}
Anchor to Step 9: Make sure redirects are properly url encodedStep 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.
Link
/app/routes/($locale).products.$productHandle.js
export async function loader({params, request, context}) {
const {productHandle} = params; // productHandle = 'スノーボード'
...
if (noSelectedProductVariant) {
// Use URL to prevent accidental double url encoding
const newUrl = new URL(
`/products/${'{'}productHandle{'}'}?${firstVariantSearchParams.toString()}`,
'http://example.com' // Any domain to satisfy the URL api
);
// Redirect to '/products/%E3%82%B9%E3%83%8E%E3%83%BC%E3%83%9C%E3%83%BC%E3%83%89?Size=154cm&Color=Syntax'
throw redirect(newUrl.pathname + newUrl.search, 302);
}
...
export async function loader({params, request, context}: LoaderArgs) {
const {productHandle} = params; // productHandle = 'スノーボード'
...
if (noSelectedProductVariant) {
// Use URL to prevent accidental double url encoding
const newUrl = new URL(
`/products/${'{'}productHandle{'}'}?${firstVariantSearchParams.toString()}`,
'http://example.com' // Any domain to satisfy the URL api
);
// Redirect to '/products/%E3%82%B9%E3%83%8E%E3%83%BC%E3%83%9C%E3%83%BC%E3%83%89?Size=154cm&Color=Syntax'
throw redirect(newUrl.pathname + newUrl.search, 302);
}
...
Anchor to Next stepsNext steps
- Create a country selector: Learn how to setup a country selector to allow users to choose their own country.