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:
- URL parser and route tree.
createHydrogenContextStorefront i18n.- Weaverse client/storefront i18n and
loadPage({locale}). - Root loader,
<html lang>and<html dir>. - Link helpers, forms, server redirects, Storefront redirects, and
.dataroutes. - Cart creation/mutations, buyer identity, country selector, and checkout redirect.
- Customer Account login, unauthorized redirect, and logout URI.
- Canonical, hreflang, sitemap, robots, and CMS SEO composition.
- 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
langanddirfrom 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:
- Live Studio design-mode override.
- Persisted Translation Manager override.
- Genuine legacy merchant setting retained for migration compatibility.
- 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