Overview
Shopify Markets helps merchants expand their business to a global audience by creating shopping experiences in local languages and currencies.
Weaverse provides a streamlined solution for creating and managing multilingual storefronts. This guide walks you through the process of setting up localization in your Hydrogen theme with Weaverse, allowing you to customize content for various markets and audiences.
Quick Demo
For a quick overview of the localization process, watch this video demonstration:
Prerequisites
Before implementing localization, ensure your project is up-to-date with the latest versions of the Hydrogen library and the @weaverse/hydrogen
package:
npx shopify hydrogen upgradenpm install @weaverse/hydrogen@latest
Implementation Steps
Step 1: Add a Country Selector
Follow Shopify’s Country Selector guide to integrate a CountrySelector
component into your Hydrogen storefront. This feature allows users to switch between markets and languages seamlessly.
Step 2: Configure Localization in the Weaverse Theme Schema
Update your theme schema to include localization settings. Modify the schema.server.ts
file to define i18n
configurations:
import type { HydrogenThemeSchema } from "@weaverse/hydrogen";import { COUNTRIES } from "~/utils/const";
export let themeSchema: HydrogenThemeSchema = { // ... other schema properties i18n: { urlStructure: "url-path", // "url-path", "subdomain", or "top-level-domain" shopLocales: Object.entries(COUNTRIES).map( ([pathPrefix, { label, language, country }]) => { return { language, // Required country, // Required pathPrefix: pathPrefix === "default" ? "" : pathPrefix, // Optional, but recommended for better navigation inside Weaverse Studio label, // Optional }; }, ), },};
The i18n
object contains the following properties:
-
urlStructure
: Defines the URL structure for localized content. Options include:url-path
: Uses path prefixes (e.g.,/en-us
,/fr-ca
) for different locales.subdomain
: Uses subdomains (e.g.,en.example.com
,fr.example.com
).top-level-domain
: Uses top-level domains (e.g.,example.fr
,example.de
).
Weaverse currently supports
url-path
structure. The other two options are under construction and will be available in future releases soon. -
shopLocales
: An array of locale objects, each containing:language
(Required): The language code (e.g.,en
,fr
).country
(Required): The country code (e.g.,US
,CA
).pathPrefix
(Optional, Recommended): An optional path prefix for the locale. It helps in better navigation inside Weaverse Studio. If not provided, it will be computed based on thelanguage
andcountry
codes.label
(Optional): An optional label for the locale, which can be used for display purposes.
Step 3: Manage Localized Content in Weaverse Studio
After integrating the CountrySelector
component and configuring the theme schema, use Weaverse Studio to manage localized content effectively:
a. Switch Between Markets/Locales
- Open your site in Weaverse Studio.
- Use the Country Selector to switch to the desired market or locale.
- You will be prompted to create a localized version of the selected page.
Note: if you don't see the dropdown, but only see a popup like the one below, it means that you have not set up the i18n
object in your theme schema. Please refer to the previous step to set it up.
b. Create Localized Pages
-
When switching to a new market, a modal will appear prompting you to create a localized version of the current page.
-
Click on "Create localized page" to generate a specific version for the chosen market.
-
Localized pages are independent of the default version, ensuring changes apply only to the selected locale and you can revert to the default version at any time.
-
If the modal does not appear, you can manually click on the "Create localized page" button next to the Country Selector in the top bar of Weaverse Studio.
c. Revert to Default Content
-
If you want to revert a localized page to the default version, you can do so easily.
-
Open the localized page in Weaverse Studio.
-
Click on the "Reset to default" button next to the Country Selector.
-
A confirmation modal will appear. Click "Reset" to confirm the action.
Please note that this action cannot be undone.
Benefits of Markets/Localization
Using Weaverse’s localization capabilities, you can:
- Deliver market-specific content while maintaining a global default version.
- Easily manage and update localized content for specific markets.
- Preview localized storefronts to ensure alignment with audience preferences.
- Revert localized pages to default content when necessary.
Conclusion
Weaverse simplifies the localization process, enabling you to efficiently manage multilingual content and provide tailored shopping experiences. By following this guide, you can ensure your storefront meets the needs of diverse markets and audiences.