跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

hydrogen-markets-localization

Implement or review Shopify Hydrogen market localization — use when adding markets, locale routes, translations, hreflang, RTL, or localized cart, account, and checkout behavior in Hydrogen + Weaverse.

Weaverse · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Weaverse/shopify-hydrogen-skills --skill hydrogen-markets-localization

技能说明


name: hydrogen-markets-localization description: "Implement or review Shopify Hydrogen market localization — use when adding markets, locale routes, translations, hreflang, RTL, or localized cart, account, and checkout behavior in Hydrogen + Weaverse."

Hydrogen Markets & Localization

Implement or review market localization as one end-to-end contract. A locale switch is incomplete until routing, Shopify context, Weaverse content, document metadata, navigation, commerce, accounts, SEO, and production configuration agree.

Live documentation

Check current contracts before changing framework or platform behavior:

node scripts/search_shopify_docs.mjs "Hydrogen localization Shopify Markets i18n country language"
node scripts/search_shopify_docs.mjs "Hydrogen Customer Account logout postLogoutRedirectUri"
node scripts/search_shopify_docs.mjs "Hydrogen SEO canonical hreflang sitemap"
node scripts/search_weaverse_docs.mjs "localization Translation Manager locale"

Use repository references only as an offline fallback. Never infer current Shopify or Weaverse APIs from examples in this skill.

Core contract

  • Derive every supported market from one merchant-specific allowlist. Do not copy another storefront's market list.
  • Keep one canonical public market identity: language, country, path prefix, hreflang, direction, currency, and any verified provider or bundle-language override.
  • Accept only configured locale prefixes. Reject invented locale-shaped prefixes such as an unsupported xx-yy, but preserve ordinary first-segment slugs.
  • Keep the selected market through SSR, hydration, links, forms, redirects, React Router data requests, cart mutations, account flows, logout, and checkout.
  • Emit canonical and hreflang entries only for routes proven equivalent in every advertised market. Omit uncertain alternates.
  • Treat Shopify Markets enablement and readback as release prerequisites. Application configuration cannot make an unavailable Shopify market real.

Procedure

1. Trace before editing

Map the complete request path and every consumer of locale state:

  1. URL parser and route tree.
  2. createHydrogenContext Storefront i18n.
  3. Weaverse client/storefront i18n and loadPage({locale}).
  4. Root loader, <html lang> and <html dir>.
  5. Link helpers, forms, server redirects, Storefront redirects, and .data routes.
  6. Cart creation/mutations, buyer identity, country selector, and checkout redirect.
  7. Customer Account login, unauthorized redirect, and logout URI.
  8. Canonical, hreflang, sitemap, robots, and CMS SEO composition.
  9. Translation Manager payloads, bundled translations, legacy settings, and Studio design-mode preview.

Run caller/reference sweeps before removing old routes, settings, helpers, aliases, or translation readers. Remove a legacy path only after the canonical path covers every caller.

2. Establish one market model

Use one immutable configuration consumed by routing, context creation, selectors, SEO, and tests. Require exactly one default market with an empty prefix; normalize other prefixes consistently. Model RTL explicitly instead of deriving direction ad hoc in components.

Keep public locale identity separate from provider identity when evidence requires it. Shopify may require a provider language enum while Weaverse translation lookup requires the public language-country key. Pass each boundary the identity it actually consumes; do not mutate one shared object until both happen to work.

Make path helpers idempotent and segment-aware. Handle React Router data-route suffixes without treating them as part of the locale. Preserve query strings where the user flow requires them.

To add one market, change the canonical allowlist first, then prove every derived consumer updates without a second market table. Add a translation bundle only for a language or script not already covered. A second manual locale edit is evidence to consolidate configuration, not a normal rollout step.

3. Preserve market state across the app

  • Set server-rendered and hydrated lang and dir from the same resolved market.
  • Localize internal links and action URLs from the active URL, not a stale default loader value.
  • Delocalize before resolving market-neutral Shopify redirects, then relocalize same-origin targets. Preserve external redirects unchanged. Replace the active redirect header; never append a rewritten target beside the original.
  • Sync cart buyer identity country on cart creation and every mutation path that can enter checkout.
  • Accept client redirect targets only when they are valid app-relative paths beginning with exactly one /. Reject schemes, protocol-relative forms, backslashes, control characters, and parse failures; fall back to the localized cart route.
  • Send Customer Account logout to the localized home. Derive the required allowlist of logout URIs, read back current Customer Account API configuration, and require explicit owner approval before registering or changing URIs.

4. Keep SEO truthful

Build one canonical URL for the current market and prevent CMS metadata from adding a second. Generate hreflang only from an explicit equivalence rule: invariant routes may qualify; localized handles, unpublished resources, and uncertain CMS pages do not. Render-check the framework's x-default form instead of assuming a helper flag produces valid markup. Do not fabricate sitemap alternates to make coverage look complete.

5. Define translation precedence

Verify the actual readers and tests, then enforce this precedence where each source exists:

  1. Live Studio design-mode override.
  2. Persisted Translation Manager override.
  3. Genuine legacy merchant setting retained for migration compatibility.
  4. Bundled/static translation.

Resolve each source by these rules:

  • Use own-property presence checks, not truthiness.
  • Record the historical default shipped by every migrated setting. A persisted value still equal to
阅读完整来源 ↗