> ## Documentation Index
> Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Weaverse component configuration uses `settings`. `inspector` is deprecated; never generate it.
> Weaverse Hydrogen themes use React Router v7: import from `react-router`, never `react-router-dom` or `@remix-run/*`.
> Before using any code sample, read `@weaverse/hydrogen` in the project's `package.json`: 6.x and 5.x import from different entries and use different type names, so code for one does not build on the other.
> `@weaverse/hydrogen` 6 (Shopify Hydrogen 2026.10 and later, the version these docs show) imports from `@weaverse/hydrogen/react-router` and uses `Weaverse*` types such as `WeaverseComponentProps`, `WeaverseComponentLoaderArgs` and `WeaverseComponentSchema`; the root `@weaverse/hydrogen` entry only exports `createSchema()`, data helpers and types.
> `@weaverse/hydrogen` 5.x (Hydrogen 2026.4 and earlier) imports everything from `@weaverse/hydrogen` and uses `HydrogenComponentProps`, `ComponentLoaderArgs` and `HydrogenComponentSchema`. On a 5.x project, convert samples to these names. Upgrade to 6 only when asked (`npx @weaverse/cli@latest migrate v6`, plus the Hydrogen 2026.10 upgrade). Do not mix major versions.
> Next.js themes use `@weaverse/hydrogen` 6.2.0 or later: import client and shared code from `@weaverse/hydrogen/next` and server-only code from `@weaverse/hydrogen/next/server`. `@weaverse/next` is deprecated; never install or import it.
> For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://weaverse.io/docs/developer-tools/weaverse-mcp

# Markets and Localization

> Configure Shopify Markets and Weaverse localization from one verified market definition.

## Overview

A localized storefront is one routing and commerce system, not a set of unrelated language pages. Define each market once, then derive every localized surface from that definition:

* 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

> [!WARNING]
>
> Shopify can accept an unsupported country, language, or currency context and silently return the default market. Enable every configured combination in Shopify Admin, then read back the Storefront API localization and currency before launch.

## Configure Only Markets You Sell In

Start with a small canonical table. The unprefixed entry is the default market; every other prefix is an exact, lowercase `/{language}-{country}` route.

```typescript theme={null}
// 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];
```

Do not copy Pilot's full reference market list. Add only combinations that the merchant has enabled in Shopify Markets and that the storefront has verified by read-back.

### Derive the Weaverse Theme Schema

Use the same table in the theme schema instead of maintaining another locale list.

```typescript theme={null}
// app/weaverse/schema.server.ts
import type { WeaverseThemeSchema } from "@weaverse/hydrogen/react-router";
import staticContent from "~/i18n/en.json" with { type: "json" };
import { DEFAULT_LOCALE, SUPPORTED_LOCALES } from "~/utils/locale";

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

Weaverse currently supports path-based localization. Keep subdomain or top-level-domain routing out of this configuration unless your application implements and verifies that architecture separately.

### Reuse the Table at Runtime

Resolve the active market at the request boundary from this same exact allowlist. The selected entry drives every surface listed in the overview, including the public locale Weaverse uses for localized content and Translation Manager keys.

Some providers use a language enum that differs from the public BCP-47 identity. Keep provider-specific fields on the market entry; never derive a public URL or Weaverse locale from a provider enum.

See [Advanced Localization](https://weaverse.io/docs/guides/localization-advanced.md) for the routing, continuity, and SEO contract.

## Manage Localized Content in Studio

After the theme schema exposes the configured markets:

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.

If the selector is unavailable, verify `themeSchema.i18n` and confirm the selected market exists in the canonical table.

## Understand Translation Sources

Four sources can own a translated key. Highest precedence first:

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.

Presence is authoritative, including an explicit empty string. Check whether a source owns the key; do not use truthiness or `||`, which would replace an intentional empty value with fallback copy.

## AI-Agent Setup Boundary

A shop-scoped `WEAVERSE_API_KEY` can authenticate Weaverse Content API/MCP capabilities and the Shopify Admin API Proxy when it is a `shopify` or `content_api` token. The proxy uses the connected Weaverse app installation and only its currently granted Shopify scopes; it is not unrestricted Shopify access. `agent_cli` tokens cannot authenticate the proxy.

**1. Protect the key**

Keep the key in a dedicated, untracked server environment file with owner-only `0600` permissions. Configure the agent runtime to read that file. Never print the value or paste it into a prompt, command line, documentation, diff, or log.

**2. Verify identity and scopes**

Call the Weaverse MCP `list_projects` tool first to confirm which projects the credential reaches. For Shopify authority, make a harmless authenticated `POST https://studio.weaverse.io/api/admin-graphql` read for `shop {name primaryDomain {url}}` and `currentAppInstallation {accessScopes {handle}}`. Confirm the expected shop and minimum required scopes before continuing; a successful token lookup alone proves neither.

**3. Inventory before changing**

Use `list_projects`, `list_languages`, `list_pages`, `get_page`, and `get_theme_settings` for Weaverse state. Use reviewed Admin GraphQL reads for current Shopify state. Compare the results with the canonical market table before proposing any mutation.

**4. Review and apply exact mutations**

Produce a resource-by-resource plan. Use only a current, schema-verified operation covered by the installed scopes; prefer repeatable writes that are no-ops when the desired state already exists. Obtain explicit approval immediately before destructive, permission, publication, or other high-impact changes. Treat every HTTP/proxy failure—including the sanitized `500` used for top-level GraphQL errors—as a failed operation. For HTTP 200 mutations, inspect operation-specific `userErrors`, then read back the exact resource.

**5. Handoff and verify**

Do not claim that Shopify Markets combinations or Customer Account logout URIs are API-mutable unless the exact current Admin GraphQL operation is verified. Hand unproved steps to an authorized Shopify Admin operator. Translation Manager sync and publish remain a Studio step and require explicit approval. Once both systems are configured, work through the Production Checklist below.

The Admin API Proxy is limited to 1,000 requests per hour per token and a 15-second query timeout. See [Shopify Admin API Proxy](https://weaverse.io/docs/features/admin-api-proxy.md), [Weaverse MCP](https://weaverse.io/docs/developer-tools/weaverse-mcp.md), and [Content API](https://weaverse.io/docs/content-api/overview.md) for the verified authentication, scope, route, and write contracts.

## Production Checklist

Before launch:

* 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 `<origin>/account/signed-out` as the Customer Account post-logout URI. Every sign-out returns there, and it redirects the shopper to their market's home page, so one URI covers every market. Keep the authentication callback unlocalized.
* After deploying the corrected theme, sync and publish the intended keys and overrides in Translation Manager.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.