Skip to main content

​
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: Localization Demo

​
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 upgrade
npm 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 the language and country 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. Switch Markets inside Weaverse Studio
  • 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. Read market setup guide

​
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. Create Localized Page modal
  • 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. Create Localized Page button

​
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. Reset to Default button
  • A confirmation modal will appear. Click “Reset” to confirm the action. Reset to Default 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.

​
Technical Implementation

While the Studio workflow above covers the visual management of localized content, understanding the technical implementation helps developers customize and extend localization functionality.

​
How Locale Detection Works

Weaverse automatically determines the current locale through your theme’s i18n configuration and Hydrogen’s storefront context. The loadPage() function uses this information to fetch the appropriate localized content. Connection between theme schema and loadPage(): 
// Your theme schema i18n config
export let themeSchema: HydrogenThemeSchema = {
  i18n: {
    urlStructure: "url-path",
    shopLocales: [
      {
        language: "en",
        country: "US",
        pathPrefix: "",
        label: "English (US)",
      },
      {
        language: "sv",
        country: "SE",
        pathPrefix: "sv-se",
        label: "Svenska",
      },
    ],
  },
};

// In your route loader
export async function loader({ context }: LoaderFunctionArgs) {
  let { weaverse } = context;

  // Weaverse automatically detects locale from context.storefront.i18n
  let weaverseData = await weaverse.loadPage({
    type: "PRODUCT",
    handle: productHandle,
    // locale auto-detected from pathPrefix (e.g., "sv-se")
  });

  return { weaverseData };
}

​
Explicit Locale Control

For advanced use cases, you can explicitly specify the locale in loadPage(): 
// Explicitly load Swedish content
let weaverseData = await weaverse.loadPage({
  type: "PRODUCT",
  handle: productHandle,
  locale: "sv-se", // Override auto-detection
});
When to use explicit locale:
  • Custom routing logic determines locale
  • Loading content for a different locale than the current page
  • Background jobs or admin tools
  • Cross-locale content comparison
See the Advanced Localization Guide for complete technical details on locale detection methods and the locale parameter.

​
Locale Format Standards

Weaverse uses the standard language-country format (lowercase, hyphen-separated):
  • Format: language-country (e.g., sv-se, fr-ca, de-de)
  • Language: ISO 639-1 code (2 letters)
  • Country: ISO 3166-1 alpha-2 code (2 letters)
Examples:
  • sv-se - Swedish (sv) in Sweden (se)
  • fr-ca - French (fr) in Canada (ca)
  • en-gb - English (en) in United Kingdom (gb)

​
Limitations of Single-Project Approach

While the single-project approach works well for most use cases, it has some limitations:
  • No per-locale theme settings: Global theme settings (colors, fonts, layouts) apply to all locales
  • URL structure constraints: Best with url-path structure (/sv-se/...); limited support for subdomains or top-level domains
  • Shared page routing: All locales share the same page structure and navigation

​
Alternative: Multi-Project Architecture

For advanced localization requirements, Weaverse supports a multi-project approach where each market or locale has its own dedicated project. When to use multi-project:
  • Different branding or theme settings per market
  • Top-level domain structure (mystore.se, mystore.fr)
  • Market-specific page structures
  • A/B testing different configurations
Setup example: 
// server.ts or weaverse initialization
const weaverse = new WeaverseClient({
  ...hydrogenContext,
  request,
  cache,
  themeSchema,
  components,
  projectId: () => {
    let origin = request.url.origin;

    if (origin === "https://mystore.se") {
      return "project-sweden-123"; // Swedish market project
    } else if (origin === "https://mystore.fr") {
      return "project-france-456"; // French market project
    } else {
      return "project-default-789"; // Default market
    }
  },
});
Multi-project workflow:
  1. Create your original project and develop your storefront
  2. Duplicate the project in Weaverse Studio for each market/locale
  3. Customize each project independently (content, theme settings, pages)
  4. Use projectId logic to route to the appropriate project based on domain or custom criteria
  5. Import/export content between projects as needed for coordination
Benefits of multi-project:
  • Independent global theme settings per market
  • Different page structures and navigation per locale
  • Support for any URL structure (top-level domains, subdomains, custom routing)
  • Complete Studio isolation per market
  • A/B testing and staged rollouts
See the Multi-Project Architecture Guide for comprehensive documentation on multi-project setup, including A/B testing, multi-brand storefronts, advanced routing patterns, and step-by-step migration guides.

​
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.