SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场hydrogen-markets-localization

hydrogen-markets-localization

前端与建站

查看项目

更新于 10-16 02:10

技能介绍

Hydrogen Markets & Localization 是一个用于实现或审查 Shopify Hydrogen 市场本地化的技能。其核心主张是：本地化必须作为一份端到端契约来处理——一次语言切换只有在路由、Shopify 上下文、Weaverse 内容、文档元数据、导航、商务、账户、SEO 与生产配置全部一致时才算完整。

用途 该技能面向需要在 Hydrogen 店铺中新增市场、语言路由、翻译、hreflang、RTL，或本地化购物车、账户与结账流程的场景。它同时适用于实现与审查两类工作。

主要能力与核心契约

  • 从一份商家专属白名单派生所有受支持市场，不复制其他店铺的市场列表。
  • 保持唯一的公开市场身份：语言、国家、路径前缀、hreflang、方向、货币，以及任何经验证的提供商或 bundle 语言覆盖。
  • 只接受已配置的 locale 前缀，拒绝虚构的 locale 形状前缀（如不受支持的 xx-yy），但保留普通的首段 slug。
  • 在 SSR、水合、链接、表单、重定向、React Router 数据请求、购物车变更、账户流程、登出与结账中保持所选市场。
  • 只对在每个已宣传市场中都被证明等价的路线输出 canonical 与 hreflang 条目，不确定的替代项一律省略。
  • 将 Shopify Markets 的启用与回读视为发布前置条件；应用配置无法让一个不可用的 Shopify 市场变为真实存在。

使用方式（流程要点）

  1. 编辑前先追踪：梳理完整请求路径与 locale 状态的所有消费者，包括 URL 解析器与路由树、createHydrogenContext Storefront i18n、Weaverse 客户端/店铺 i18n 与 loadPage({locale})、根 loader、<html lang> 与 <html dir>、链接助手、表单、服务端重定向、Storefront 重定向、.data 路由、购物车创建/变更、买家身份、国家选择器、结账重定向、Customer Account 登录/未授权重定向/登出 URI、canonical/hreflang/sitemap/robots 与 CMS SEO 组合、Translation Manager 载荷、bundle 翻译、遗留设置与 Studio 设计模式预览。删除旧路由、设置、助手、别名或翻译读取器前先做调用方/引用扫描。
  2. 建立单一市场模型：使用一份不可变配置供路由、上下文创建、选择器、SEO 与测试消费；要求恰好一个空前缀的默认市场，其他前缀一致规范化；显式建模 RTL，而非在组件中临时推导方向。在证据要求时，将公开 locale 身份与提供商身份分开。路径助手需幂等且感知分段，处理 React Router 数据路由后缀而不将其视为 locale 的一部分，并在用户流程需要时保留查询字符串。新增一个市场时先改规范白名单，再证明所有派生消费者无需第二张市场表即可更新。
  3. 在应用中保持市场状态：从同一已解析市场设置服务端渲染与水合的 lang 和 dir；从当前 URL 而非过期的默认 loader 值本地化内部链接与操作 URL；解析市场无关的 Shopify 重定向前先去本地化，再对同源目标重新本地化，外部重定向保持不变，替换活动重定向头而非追加；在购物车创建及每条可进入结账的变更路径上同步购物车买家身份国家；仅接受以恰好一个 / 开头的有效应用相对路径作为客户端重定向目标，拒绝 scheme、协议相对形式、反斜杠、控制字符与解析失败，回退到本地化购物车路由；将 Customer Account 登出指向本地化首页，派生所需登出 URI 白名单，回读当前 Customer Account API 配置，并在注册或更改 URI 前获得明确的所有者批准。
  4. 保持 SEO 真实：为当前市场构建一个 canonical URL，防止 CMS 元数据添加第二个；仅从显式等价规则生成 hreflang（不变路由可能符合，本地化 handle、未发布资源与不确定的 CMS 页面不符合）；渲染检查框架的 x-default 形式，而非假设某个助手标志会生成有效标记；不要为让覆盖率看起来完整而虚构 sitemap 替代项。
  5. 定义翻译优先级：在每种来源存在处强制执行——实时 Studio 设计模式覆盖、持久化的 Translation Manager 覆盖、为迁移兼容保留的真实遗留商家设置、bundle/静态翻译。解析规则包括：使用自有属性存在性检查而非真值判断；记录每个被迁移设置的历史默认值，仍等于该默认值的持久化值不构成商家意图证明，必须向下穿透；继承值与未持久化的 schema 默认值视为不存在；显式存储的空字符串视为“清除此文案”，不得向下穿透；将 bundle 文案与商家覆盖来源分开；仅当所有渲染面都使用共享读取器后才删除遗留设置与旁路 props。
  6. 证明平台配置：对每个已配置市场探测生产 Shopify 边界并回读有效国家、语言与货币，Shopify 静默回退时发布失败；同时验证 Weaverse 收到 Translation Manager 使用的公开 locale 键、Translation Manager 主题键同步为最新且已发布覆盖生效、每个本地化 Customer Account 登出 URI 均被允许、演示/项目同步、CI、部署与线上店铺状态对应已测试提交。生产证明默认只读；更改 Shopify、Customer Account、Weaverse、购物车、会话或结账状态前，确认确切环境、身份、范围与值并获得明确所有者批准；使用专用测试身份，绝不因本地化验证而下付费订单。

AI 代理执行路径 Weaverse Shopify Admin API 代理是一个有作用域的权限桥。使用前验证其当前挂载路由；Builder 实现暴露：POST https://studio.weaverse.io/api/admin-graphql，携带 GraphQL 查询或变更与变量；Authorization: Bearer <WEAVERSE_API_KEY>，使用类型为 shopify 或 content_api 的店铺作用域令牌，agent_cli 令牌会被拒绝；Shopify 操作限于已连接的 Weaverse 应用安装与商家在 Weaverse Dashboard → Settings → Shopify Admin API Proxy → Manage Scopes 中授予的作用域；代理限制为每令牌每小时 1000 次请求，查询超时 15 秒。这是真实的 Shopify Admin 访问，但并非对所有 Shopify 资源的无限制访问。按以下顺序执行：发现能力、安全准备密钥、读取身份与作用域、起草经审查的变更计划、幂等变更、精确回读、门控发布、发布后验证。若密钥、最低 Shopify 作用域或经验证的变更不可用，完成所有可达的代码与只读检查，将相应生产设置标记为未证明，并在验证清单中给出确切的管理员交接。绝不声称市场已启用或端到端本地化已成功。

验证与相关技能 读取 references/verification-checklist.md 并仅执行适用于该店铺的检查；从聚焦回归开始，再演练真实开发服务器与生产边界；市场列表与预期货币保持商家专属。相关技能：shopify-hydrogen 用于当前 Hydrogen 上下文、购物车、SEO 与 sitemap API；weaverse-hydrogen 用于 Weaverse 客户端与页面加载 API；weaverse-content-api 用于经认证的按 locale 内容读写；generating-weaverse-project-json 用于导入时 defaultLocale 或页面分配需要变更时。

限制 该技能依赖同级的 shopify-hydrogen 技能提供的辅助脚本（../shopify-hydrogen/scripts/）。若单独安装本技能，该文件夹缺失，相关命令会以 MODULE_NOT_FOUND 失败，需先运行 npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen 添加辅助脚本；references/ 文件可作为离线回退。仓库引用仅作离线回退，绝不从本技能示例推断当前 Shopify 或 Weaverse API。