hydrogen-markets-localization

Hydrogen Markets 与本地化

将市场本地化作为一项端到端契约来实现或审查。只有当路由、Shopify 上下文、Weaverse 内容、文档元数据、导航、电商功能、账户、SEO 和生产环境配置彼此一致时，语言区域切换才算完整。

实时文档

请在此技能自身的文件夹中运行以下命令。辅助脚本随同级的 shopify-hydrogen 技能一起提供；只要安装了整个工具包，../shopify-hydrogen/scripts/ 就会存在。

如果你单独安装了此技能，该文件夹将不存在，以下命令会因 MODULE_NOT_FOUND 而失败。请添加一次辅助脚本：

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

此技能中的 references/ 文件仍可作为离线备用资料使用，你也可以选择不安装该技能。

更改框架或平台行为之前，请先检查当前契约：

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

仅将仓库参考资料用作离线备用资料。切勿根据此技能中的示例推断当前 Shopify 或 Weaverse API。

核心契约

• 从一个商家专属的允许列表中推导出所有受支持的市场。不要复制其他店面的市场列表。
• 保持唯一的规范公开市场标识：语言、国家/地区、路径前缀、hreflang、方向、货币，以及任何经过验证的提供方或捆绑包语言覆盖项。
• 仅接受已配置的语言区域前缀。拒绝类似 xx-yy 的未配置语言区域前缀，但保留普通的首段路径。
• 在 SSR、水合、链接、表单、重定向、React Router 数据请求、购物车变更、账户流程、登出和结账过程中，始终保留所选市场。
• 仅对已证明在所有声明支持的市场中等效的路由输出 canonical 和 hreflang 条目。对不确定的替代项不予输出。
• 将启用 Shopify Markets 并读取回确认结果视为发布前提条件。应用配置无法让不可用的 Shopify 市场变为可用。

流程

1. 修改前先追踪

梳理完整的请求路径以及所有消费语言区域状态的环节：

1. URL 解析器和路由树。
2. createHydrogenContext Storefront i18n。
3. Weaverse 客户端/Storefront i18n 和 loadPage({locale})。
4. Root loader、<html lang> 和 <html dir>。
5. 链接辅助函数、表单、服务端重定向、Storefront 重定向和 .data 路由。
6. 购物车创建/变更、买家身份、国家/地区选择器和结账重定向。
7. Customer Account 登录、未授权重定向和登出 URI。
8. canonical、hreflang、sitemap、robots 和 CMS SEO 组合。
9. Translation Manager 负载、捆绑翻译、旧版设置以及 Studio 设计模式预览。

移除旧路由、设置、辅助函数、别名或翻译读取器之前，先全面搜索调用方和引用。只有在规范路径覆盖所有调用方后，才能移除旧路径。

2. 建立统一的市场模型

使用一份不可变配置，供路由、上下文创建、选择器、SEO 和测试共同使用。必须且只能有一个默认市场，其前缀为空；其他前缀应采用一致的规范化方式。显式建模 RTL，而不是在组件中临时推导方向。

在证据表明有必要时，将公开语言区域标识与提供方标识分开。Shopify 可能要求使用提供方语言枚举，而 Weaverse 翻译查找则需要公开的语言-国家/地区键。向每个边界传递其实际使用的标识；不要为了让两边都能工作而修改同一个共享对象。

路径辅助函数应具备幂等性，并能识别路径段。处理 React Router 数据路由后缀时，不要将其视为语言区域的一部分。在用户流程需要时保留查询字符串。

添加一个市场时，先修改规范允许列表，然后验证每个派生消费者都会随之更新，而无需再维护第二份市场表。仅当某种语言或文字系统尚未覆盖时，才添加翻译包。若需要第二处手动修改语言区域，说明配置应当整合，而不是正常的发布步骤。

3. 在整个应用中保留市场状态

• 根据同一个已解析的市场设置服务端渲染和水合后的 lang 与 dir。
• 根据当前 URL（而非过时的默认加载器值）本地化内部链接和操作 URL。
• 在解析与市场无关的 Shopify 重定向前，先移除本地化信息；然后重新本地化同源目标。保持外部重定向不变。替换当前生效的重定向标头；切勿将改写后的目标追加到原始目标旁边。
• 在创建购物车时，以及每个可能进入结账流程的变更路径中，同步购物车买家身份的国家/地区。
• 仅接受以且仅以一个 / 开头的有效应用相对路径作为客户端重定向目标。拒绝方案、协议相对形式、反斜杠、控制字符和解析失败的情况；并回退到本地化购物车路由。
• 将 Customer Account 登出请求发送到本地化首页。推导所需的登出 URI 允许列表，读取当前 Customer Account API 配置，并要求所有者明确批准后再注册或更改 URI。

4. 保持 SEO 信息准确

为当前市场构建一个规范 URL，并防止 CMS 元数据添加第二个规范 URL。仅依据明确的等效规则生成 hreflang：不变的路由可能符合条件；本地化句柄、未发布的资源和不确定的 CMS 页面则不符合。渲染检查框架生成的 x-default 形式，不要想当然地认为某个辅助函数标记会生成有效标记。不要伪造站点地图的备用链接来让覆盖范围看起来更完整。

5. 明确翻译优先级

核实实际读取方和测试，然后在各来源存在时遵循以下优先级：

1. Studio 设计模式中的实时覆盖值。
2. Translation Manager 中已持久化的覆盖值。
3. 为兼容迁移而保留的真实旧版商家设置。
4. 捆绑/静态翻译。

按照以下规则解析每个来源：

• 检查自有属性是否存在，而不是检查其真值。
• 记录每个已迁移设置历史上随附的默认值。仍等于该默认值的已持久化值，并不能证明是商家意图，必须继续向下回退。
• 将继承的值和未持久化的架构默认值视为不存在。
• 将明确存储的空字符串视为“清除此文案”；不得继续回退。
• 将捆绑文案与商家覆盖值的来源信息分开保存。
• 只有在所有渲染界面都使用共享读取器后，才能删除旧版设置和绕过属性。

6. 验证平台配置

对于每个已配置的市场，都要探测 Shopify 生产环境边界，并读取生效的国家/地区、语言和货币。如果 Shopify 静默回退，则阻止发布。还要验证：

• Weaverse 收到 Translation Manager 使用的公开语言区域键。
• Translation Manager 的主题键同步为最新状态，且已发布的覆盖值优先生效。
• 每个本地化的 Customer Account 登出 URI 都在允许列表中。
• Demo/项目同步、CI、部署和实时店面状态均对应于已测试的提交。

默认情况下，生产环境验证应为只读。在更改 Shopify、Customer Account、Weaverse、购物车、会话或结账状态之前，确认确切的环境、身份、范围和值，并取得所有者的明确批准。使用专用测试身份，切勿为验证本地化而下付费订单。

AI Agent 执行路径

Weaverse Shopify Admin API 代理是一个限定权限的桥接层。使用前请确认其当前挂载的路由；Builder 实现提供：

• POST https://studio.weaverse.io/api/admin-graphql，携带 GraphQL query 或 mutation 及变量。
• 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 资源。请为已验证的操作申请所需的最小权限。Storefront API 访问可以证明店面行为符合预期，但不能取代 Admin 权限。

按以下顺序执行：

1. 发现能力。 检查仓库路由、脚本和已挂载的工具。获取最新的权威 Shopify/Weaverse 文档。记录每项读写操作对应的确切 GraphQL 操作或 Admin UI 步骤；绝不臆造 mutation、字段、端点或假定能力。除非当前 Shopify Admin GraphQL schema 或权威文档证实了确切操作，否则不得声称 Markets 设置、已启用的语言、国家/货币或 Customer Account 登出 URL 可以修改。
2. 安全准备密钥。 将 WEAVERSE_API_KEY 放入未跟踪的仅供服务器使用的环境文件，并将权限设为 0600，或使用获准的凭据绑定。绝不能将其放入客户端代码、提示词、文档、URL、命令参数或日志。
3. 读取身份和权限范围。 通过已验证的代理执行无害的当前 schema 身份/店铺读取操作，并在修改前检查已授予应用的权限范围。遇到店铺不匹配、缺少最低权限、令牌类型错误、目标不明确、达到速率限制或超时，均应安全失败。
4. 拟定经审核的修改计划。 列出当前值和目标值、确切的目标 ID、已验证的 GraphQL 操作或 Admin 步骤、所需权限范围、幂等性判断条件、无操作行为、回滚方案、发布边界以及确切的回读内容。每次外部写入前都必须获得负责人明确批准；另行标明具有破坏性或高影响的更改。
5. 幂等地修改。 重新读取前置条件，跳过已符合要求的状态，并且仅应用已批准的差异。检查 HTTP/代理错误、顶层 GraphQL errors 以及 mutation 负载中的 userErrors；出现任何一项都意味着无法证明写入成功。如有状态偏移、回退、部分失败或意外响应，立即停止。
6. 精确回读。 使用独立查询，将每个已批准的国家、语言、货币、市场、本地化键和已验证的登出 URL 与计划逐一比对。不得将 mutation 响应被接受视为成功证明。
7. 设置发布门槛。 提供完整的回读结果，并请求明确的发布/部署批准。发布、部署或启用市场均属于单独的重大操作。
8. 发布后验证。 测试已批准的路由矩阵，并确认渲染的 lang/dir、保留本地化信息的导航、购物车买家身份、结账市场/货币、canonical/hreflang、站点地图策略、Translation Manager 输出以及已部署版本。请从证据中删去敏感 URL、查询参数和会话值。

如果密钥、最低 Shopify 权限或已验证的 mutation 不可用，请完成所有可执行的代码工作和只读检查，将相应的生产环境设置标记为未经验证，并在验证清单中提供准确的管理员交接说明。绝不能声称市场已启用或端到端本地化已成功。

验证

阅读 references/verification-checklist.md，仅执行适用于该店面的检查。先进行针对性回归测试，然后验证真实开发服务器和生产环境边界。市场列表和预期货币应针对具体商家设置。

相关技能

• 使用 shopify-hydrogen 获取最新的 Hydrogen 上下文、购物车、SEO 和站点地图 API。
• 使用 weaverse-hydrogen 获取 Weaverse 客户端和页面加载 API。
• 使用 weaverse-content-api 读取和写入经过身份验证的特定区域设置内容；不要在此处复述该 API 的工作流。
• 当导入时的 defaultLocale 或页面分配必须更改时，使用 generating-weaverse-project-json。