Markets and Localization

​

Overview

• URL prefixes and the exact set of supported market routes
• Shopify Storefront API country and language context
• Weaverse locale and localized page data
• links, redirects, and React Router data requests
• cart buyer identity and checkout continuity
• <html lang> and dir
• canonical URLs, hreflang, and sitemap entries

​

Configure Only Markets You Sell In

// app/utils/locale.ts
export const SUPPORTED_LOCALES = [
  {
    pathPrefix: "",
    label: "United States (USD $)",
    language: "EN",
    country: "US",
    currency: "USD",
    hreflang: "en-US",
    direction: "ltr",
  },
  {
    pathPrefix: "/fr-ca",
    label: "Canada — Français (CAD $)",
    language: "FR",
    country: "CA",
    currency: "CAD",
    hreflang: "fr-CA",
    direction: "ltr",
  },
  {
    pathPrefix: "/ar-ae",
    label: "الإمارات العربية المتحدة (AED)",
    language: "AR",
    country: "AE",
    currency: "AED",
    hreflang: "ar-AE",
    direction: "rtl",
  },
] as const;

export const DEFAULT_LOCALE = SUPPORTED_LOCALES[0];

​

Derive the Weaverse Theme Schema

// app/weaverse/schema.server.ts
import type { HydrogenThemeSchema } from "@weaverse/hydrogen";
import staticContent from "~/i18n/en.json" with { type: "json" };
import { DEFAULT_LOCALE, SUPPORTED_LOCALES } from "~/utils/locale";

export const themeSchema: HydrogenThemeSchema = {
  // ...components and settings
  i18n: {
    urlStructure: "url-path",
    defaultLocale: DEFAULT_LOCALE,
    shopLocales: SUPPORTED_LOCALES,
    translation: true,
    staticContent,
  },
};

​

Reuse the Table at Runtime

​

Manage Localized Content in Studio

1. Open the page in Weaverse Studio.
2. Choose a configured market from the market selector.
3. Create the localized page when prompted.
4. Edit and publish that market’s content.
5. Use Reset to default only when you intend to discard the localized page and return to default content.

​

Understand Translation Sources

1. Live Studio design override — the current preview edit.
2. Persisted Translation Manager override — merchant-authored.
3. Genuine legacy merchant setting — a value customized before migration. A stored value still equal to the theme’s shipped default is not merchant intent and falls through.
4. Bundled/static market translation — ships with the theme and is the final fallback.

​

AI-Agent Setup Boundary

​

Production Checklist

• Enable every configured country, language, and currency in Shopify Admin.
• Read back each combination from the Storefront API; remove any market that resolves to the default instead of the requested context.
• Confirm unsupported exact locale-shaped prefixes return 404 while ordinary slugs such as /about-us or /collections/hi-in-picks remain valid.
• Confirm market switches preserve the intended path and query and perform a document navigation so stale Weaverse data is not reused.
• Confirm links, redirects, and React Router .data requests retain the active market.
• Confirm cart buyer identity and checkout remain in the selected country and currency.
• Render the selected market’s hreflang as <html lang> and set dir="rtl" for RTL markets.
• Emit a self-canonical URL and only the hreflang alternates whose equivalent routes are known to exist. Omit uncertain alternates.
• Register the storefront origin and every served market home URI as allowed Customer Account post-logout URIs. Keep the authentication callback unlocalized.
• After deploying the corrected theme, sync and publish the intended keys and overrides in Translation Manager.