pz-cli 5.0.0__py3-none-any.whl

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/29-/345/244/232/345/233/275/350/257/255/350/250/200/350/265/204/346/272/220/346/262/273/347/220/206/344/270/216/346/214/211/351/234/200/345/212/240/350/275/275/350/247/204/350/214/203-/345/220/253/350/277/201/347/247/273/347/255/226/347/225/245.md

@@ -0,0 +1,956 @@
+# 29-多国语言资源治理与按需加载规范
+
+> 本文档用于定义 `pz` 体系下多国语言资源的正式治理边界与按需加载主链。本文档服从 `00-pz架构总纲`、`05-资源与运行目录规范`、`17-分层与扩展规范`、`21-扩展点正式协议清单` 的上位约束。
+
+## 1. 目标
+
+本文档解决三个长期问题：
+
+- 避免 `base` 持续膨胀，重新变成“全站公共垃圾桶”
+- 避免页面把整站翻译全集注入 HTML 或一次性下发给前端
+- 在不引入第二套资源协议的前提下，实现清晰的翻译 owner、稳定的 fallback 规则与按需取用能力
+
+本文档的正式目标不是“再造一套 i18n 框架”，而是在现有 `resource manifest` 主链上，补齐多国语言资源的正式治理约束。
+
+## 2. 设计哲学对齐
+
+本方案必须同时满足 `pz` 的以下设计哲学：
+
+- 最小子包是唯一正式单位，不是 `base`、不是宿主目录分组、也不是页面临时约定
+- `pz` 只保留稳定合同、发现、编译、组装与启动，不承载高层业务翻译实现
+- 一个问题只保留一种正式解决方案，不允许出现第二套翻译装配主链
+- 资源进入系统的唯一正式入口仍然是 `resource.contribution -> resource manifest`
+- Web / CLI / worker 只消费 `RuntimePlan` 与其中的 `resource_manifest`
+- 共享能力进入共享子包，业务能力进入业务子包，宿主只做装配
+
+因此：
+
+- 不允许再新增一套独立的 `translations registry`、`page resources DSL`、`surface bootstrap` 之类第二主链
+- 不允许页面自己直接扫描 `locales/`、拼接路径、维护局部 fallback 规则
+- 不允许通过“先塞进 `base`，之后再看是否迁移”作为长期治理方案
+
+## 3. 非目标
+
+本文档不做以下事情：
+
+- 不定义新的模板引擎或新的前端国际化框架
+- 不要求所有历史 key 立刻一次性迁移完成
+- 不把具体页面文案 owner 直接硬编码进 `pz` core
+- 不允许为了 i18n 治理，在 `pz` 基础层引入高层页面/业务实现
+
+## 4. 正式术语
+
+### 4.1 `locale owner`
+
+某个翻译资源的正式归属最小子包。
+
+规则：
+
+- 每个翻译 key 必须先有唯一 `locale owner`
+- `locale owner` 只能是最小子包
+- `base` 不是 owner，只是少量共享文案面的物理承载位置
+
+### 4.2 `locale bundle`
+
+运行时的最小翻译消费单位。
+
+一个 `locale bundle` 表示：
+
+- 某个 owner
+- 某个稳定文案面
+- 某个语言版本
+
+`locale bundle` 是运行时和前端正式消费的最小单位，不再以“整个语言全集”作为默认消费单位。
+
+### 4.3 `shared bundle`
+
+由共享子包持有、可被其他 bundle 显式依赖的共享翻译面。
+
+它的职责是承载跨页面、跨模块、跨业务仍然稳定复用的共享文案块。
+
+典型内容：
+
+- 导航
+- footer
+- 通用按钮
+- 共享首帧 UI
+- 共享壳层 SEO 文案
+
+### 4.4 `page-type bundle`
+
+由某个 owner app 持有、供一类页面重复复用的翻译面。
+
+它的职责是承载“同类型页面”的通用文案结构，而不是单页面独有文案。
+
+典型场景：
+
+- SEO keyword landing 页
+- tool landing 页
+- pricing landing 页
+- FAQ landing 页
+
+### 4.5 `bundle dependency`
+
+某个 bundle 允许依赖哪些共享 bundle 的正式声明。
+
+它用于限定 fallback 和按需加载边界，不允许 bundle 之间任意互相吃文案。
+
+### 4.6 `locale governance metadata`
+
+用于描述 `locale bundle`、`bundle dependency`、共享 allowlist 与消费绑定关系的标准资源元数据。
+
+正式要求：
+
+- 它必须通过 `apps.py -> extensions() -> resource.contribution` 声明
+- 它必须通过统一 resource compiler 进入 `resource_manifest`
+- 它不是新的扩展点协议，也不是页面侧独立 DSL
+
+历史说明：
+
+- `locales/config.json` 属于历史遗留设计
+- 它将“翻译内容”和“翻译治理配置”混放在 `locales/` 下
+- 本轮正式方案不保留兼容，不再作为正式声明点
+
+### 4.7 `locale consumer binding`
+
+某个正式消费单元与其允许消费的 bundle 集合之间的绑定关系。
+
+这里的“消费单元”不是宿主临时对象，而是 owner app 控制下的正式渲染单元，例如：
+
+- 路由渲染单元
+- 模板入口单元
+- 前端模块入口单元
+
+它的声明必须来自 owner app 的 `resource.contribution` 元数据，并统一编译进 `resource manifest`。
+
+### 4.8 `locale composition profile`
+
+用于描述一类页面或渲染单元应如何组合多个 bundle 的结构化配置。
+
+它的设计目标是支持这类正式场景：
+
+- SEO 页面一个页面对应一个关键词
+- 新增关键词页面时，不必复制一整套翻译装配规则
+- owner app 只需新增或调整 profile 配置，即可复用既有共享 bundle 与页面 bundle 组合
+
+正式要求：
+
+- profile 必须由 owner app 在 `resource.contribution` 元数据中声明
+- profile 只能组合已声明的 bundle 与 dependency
+- profile 不得在运行时临时拼接第二套规则
+- 页面级语言事实必须收敛到 `page_supported_language`，用于约束当前页面实际支持、可注册、可输出 canonical / hreflang / sitemap 的语言范围
+- 页面语言切换 URL 必须收敛到 `page_language_alternates`，用于表达当前页面各语言版本的 canonical alternate URL；全站语言全集只称 `routing.all_supported_languages`
+
+### 4.8.1 `page_supported_language`
+
+某个 `page_config` / `page_profile` 正式支持的页面级语言集合。
+
+它用于统一约束以下能力：
+
+- `seo.provider` 暴露的 hreflang 语言范围
+- `seo.sitemap_provider` 暴露的 sitemap 语言范围
+- 页面是否对某语言实际开放
+- 页面语言切换候选语言范围
+
+正式要求：
+
+- `page_supported_language` 必须作为页面级结构化字段进入页面编译结果和请求期页面状态
+- `page_supported_language` 必须是顶层 `routing.all_supported_languages` 的子集；顶层语言全集只负责 URL 语言前缀归一化、alias 解析和系统级合法性判断
+- 若某页面只允许一个语言，则 `page_supported_language` 只能包含该语言
+- 不在 `page_supported_language` 内的语言，不得出现在页面注册、`hreflang` 或 sitemap 中
+- fallback 仅影响内容兜底，不得自动扩张 `page_supported_language`
+- 对 owner app 的正式公开面应尽量收敛到单个 `page_profile` / `page_config` 解析入口；`page_supported_language` 作为页面合同字段暴露，而不是再额外公开第二个“裸语言列表”入口
+- `seo.provider`、`seo.sitemap_provider` 等共享消费方应统一从页面编译结果或请求期页面状态读取 `page_supported_language`，不要要求业务子包分别实现多套语言解析 surface
+- 若页面级 profile 需要跨子包被共享消费，正式接入方式应是 `PageProfileProviderSpec(kind="page.profile_provider")` 扩展点，而不是业务子包在 `public.py` 继续暴露自定义 resolver
+
+### 4.8.2 `page_language_alternates`
+
+当前页面各语言版本 canonical alternate URL 的页面级投影。
+
+它用于表达“当前内容实体在某语言下的正式跳转 URL”，不由前端根据全站语言全集临时拼接。典型场景是页面 owner 在渲染前把当前页面的多语言 canonical 写入 `request.state.page_language_alternates`，共享 UI、footer 语言链接和前端 `window.changeLanguage` 消费同一个 SSR 投影。
+
+正式要求：
+
+- `page_language_alternates` 必须作为请求期页面状态或 SEO hreflang 同合同投影进入模板运行态；不得另建独立 resolver / getter 作为第二真相源
+- `page_language_alternates` 的语言成员必须来自当前页面的 `page_supported_language`
+- 若当前页面缺少 `page_language_alternates`，共享 UI 只允许按正式合同使用 SEO hreflang 投影或当前页面事实做兜底；不得用 `routing.all_supported_languages` 自动扩展当前页面可切换语言
+- 若请求期页面状态显式声明 `page_language_alternates = []`，表示该页面不提供语言切换 URL；共享 UI 层不得继续回退到模块或全站语言列表
+- `page_language_alternates` 只表达语言切换 URL，不得扩张 `hreflang`、sitemap、canonical 语言族或索引资格
+
+### 4.9 `page-local override`
+
+某个具体页面对通用 bundle 的稀疏覆盖补丁。
+
+它的职责不是保存整页全文案，而是处理极少数单页面特化字段。
+
+正式要求：
+
+- override 默认不是常规路径，而是受限例外能力
+- override 只能服务单页面特化，不得复制整页 bundle
+- override 必须与具体 profile 显式绑定
+- override 必须通过 `resource.contribution` 元数据声明，并统一编译进 `resource manifest`
+
+治理约束：
+
+- override 必须是稀疏 patch，而不是整页 JSON 副本
+- override 只允许覆盖白名单字段
+- 若 override 体积持续增大，应优先重构 page-type bundle，而不是继续 patch
+
+## 5. 正式治理边界
+
+### 5.1 owner 先于目录
+
+翻译归属必须先判 owner，再判物理目录。
+
+禁止：
+
+- 先因为“方便复用”把 key 放进 `base`
+- 先因为“页面暂时缺词”把业务 key 放进共享目录
+- 通过目录名掩盖真实 owner
+
+### 5.2 共享文案归共享子包
+
+共享站点壳、共享首帧、共享导航、共享按钮、认证、协议页等共享文案，必须归对应共享子包。
+
+典型 owner：
+
+- shared site UI owner
+- auth owner
+- site essentials / policy owner
+
+### 5.3 业务文案归业务子包
+
+首页、pricing、FAQ、tools、业务 SEO、业务 JSON-LD、业务转化文案，必须归业务子包本身。
+
+宿主或业务 app 不得把这些内容长期塞进共享 `base`。
+
+### 5.4 `base` 的正式地位
+
+`base` 不是第二业务目录，只是“共享稳定文案面”的受限承载位置。
+
+`base` 只能保留 allowlist 范围内的共享 bundle。
+
+## 6. 正式资源模型
+
+### 6.1 保持单一资源主链
+
+多国语言资源仍然属于正式 `resource.contribution` 的一部分。
+
+每个 app 继续只提交自己的：
+
+- `templates_dir`
+- `static_dir`
+- `locales_dir`
+
+统一进入 `resource manifest`。
+
+不允许：
+
+- 额外新增 `translations()` / `surfaces()` / `page_resources()` 之类第二协议
+- 在 Web 启动或请求路径中再次重扫 `locales/`
+
+### 6.2 在 `resource manifest` 上补足翻译元信息
+
+对于 `locales_dir`，正式编译链应补充但不限于以下元信息：
+
+- `owner_app`
+- `bundle_id`
+- `language`
+- `source_path`
+- `fallback_policy`
+- `bundle_dependencies`
+
+这些元信息属于 `resource manifest` 的翻译资源视图，不构成第二套装配协议。
+
+声明约束：
+
+- 上述元信息只允许来自：
+  - 标准目录布局
+  - `resource.contribution` 的结构化元数据
+- 不允许页面、模板或前端脚本在运行时自行声明 bundle / dependency / fallback
+
+推荐字段清单：
+
+- `locale_bundles`
+  - 描述当前 app 提供的 `shared bundle` 与 `page-type bundle`
+- `locale_dependencies`
+  - 描述 bundle 之间的显式依赖关系
+- `locale_consumer_bindings`
+  - 描述正式消费单元可消费哪些 bundle
+- `locale_profiles`
+  - 描述页面组合定义、SEO keyword page 组合规则与页面语言暴露集合
+- `locale_overrides`
+  - 描述受限 `page-local override`
+- `locale_allowlist`
+  - 描述当前 app 的 `base` 共享面 allowlist
+
+这些字段属于 `resource.contribution` 的正式结构化元数据建议清单。后续协议落地时，应收敛为唯一字段集合，不允许各 app 自行扩展第二套命名。
+
+### 6.3 真相源唯一
+
+翻译运行时的唯一真相源仍然是当前 `RuntimePlan.resource_manifest` 及其对应的合并产物。
+
+不允许：
+
+- import-time 绑定 merged locales
+- 模块级全局 translation manager 长期持有旧快照
+- 页面脚本绕过 manifest 直接读磁盘资源
+
+### 6.4 推荐源码布局
+
+本方案推荐把“翻译内容”和“页面组合定义”物理拆开。
+
+推荐目录：
+
+- `locales/`
+  - 只放翻译内容
+  - 推荐按 `owner / lang / bundles` 或同等清晰层次组织
+- `page_profiles/`
+  - 只放页面组合定义
+  - 推荐用于 SEO keyword page、tool landing page、FAQ landing page 这类组合型页面
+- `locale_overrides/` 或等价目录
+  - 只放受限的 page-local override
+  - 仅在确有必要时启用
+
+推荐示意：
+
+- `page_profiles/example-topic-landing.jsonc`
+- `locales/example_app/en/bundles/topic_landing.json`
+- `locales/example_app/zh-CN/bundles/topic_landing.json`
+- `locale_overrides/example-topic-landing/en.json`
+
+约束：
+
+- 目录结构只是源码组织建议，正式协议仍只认 `resource.contribution` 与编译结果
+- `page_profiles/` 不得重新变成第二套运行时装配入口
+- `locales/` 不再承担页面组合配置职责
+
+## 7. 正式消费模型
+
+### 7.1 bundle 是唯一正式消费单位
+
+运行时和前端只允许按 `locale bundle` 消费翻译资源。
+
+不允许：
+
+- 读取整个语言全集作为默认正式路径
+- 页面按目录扫描或文件名拼接来构造文案集
+
+### 7.2 页面必须按声明取用
+
+正式消费单元只能消费：
+
+- 自己所属 owner 的 bundle
+- 自己显式声明依赖的共享 bundle
+- 与当前 profile 显式绑定的 page-local override
+
+未声明的 bundle 不得被默认消费。
+
+这里的“显式声明”不是宿主局部约定，而应由 owner app 在 `resource.contribution` 元数据中声明，并由 resource compiler 编译进 `resource manifest`。
+
+### 7.3 SSR 与 CSR 统一主链
+
+正式要求：
+
+- SSR 只注入首帧所必需的最小 bundle
+- CSR 通过统一 translation facade 按 bundle 懒加载剩余翻译
+- 不再提供“页面加载时把所有翻译全集一次性注入 HTML”的正式路径
+- SEO 关键页面与其他外部可见公开页面的首屏可见文案必须以后端渲染为正式主链，不得依赖前端二次请求翻译后再补齐正文
+- 上述页面的前端翻译请求正式职责仅限于交互增强、异步组件和缺词补拉，不得反向成为首屏文案真相源
+- `admin`、内部运营页、自用后台、强登录态工作台不强制纳入这条 SEO/public 首屏翻译约束
+
+### 7.3.1 首屏后端直出约束
+
+这里的“首屏可见文案”至少包括：
+
+- 页面标题区
+- 首屏 CTA
+- 首屏正文摘要
+- FAQ 首屏可见问答
+- 首屏可见 SEO 文案块
+- 与当前页面绑定的结构化数据、meta 描述、hreflang 所依赖的稳定语言内容
+
+正式要求：
+
+- owner app 必须先按 `page_profile`、bundle 组合、当前语言与 fallback 规则，在服务端完成首屏翻译 payload 裁剪
+- 模板上下文或页面注入数据只允许携带“当前页面首屏实际需要的最小翻译集合”
+- 前端 `translation facade` 必须优先消费服务端已注入的页面级翻译 payload
+- 只有当异步组件、延后渲染区块或用户触发交互确实需要额外词条时，才允许再次请求翻译接口
+
+### 7.3.1.1 请求期运行时合同
+
+对外可见且需要 SEO 的 HTML 页面，在进入共享模板或共享翻译 facade 之前，必须先把页面翻译上下文绑定到统一的请求期合同。
+
+正式要求：
+
+- 该绑定必须由 owner app 或 site runtime 在进入模板前一次性完成
+- 共享层应优先消费请求期合同，不得要求每条路由各自重新解析一遍 `page_profile`
+- `pz` 基础层不承载这类页面装配细节；正式 helper 应放在 `pz_contrib` 或业务扩展层
+
+公共 HTML 页请求期合同至少应包含：
+
+- `request.state.lang`
+- `request.state.translation_module`
+- `request.state.page_profile`
+- `request.state.translation_bundles`
+- `request.state.client_translation_scopes`
+- `request.state.page_supported_language`
+- `request.state.page_language_alternates`
+
+约束：
+
+- `translation_bundles` 是共享翻译 facade 的正式 bundle 组合真相源
+- `client_translation_scopes` 是前端增量取词范围的正式真相源
+- `page_supported_language` 是页面注册、`hreflang`、`sitemap` 与公开索引语言范围的正式页面级真相源
+- `page_language_alternates` 是页面语言切换 URL 的正式 SSR 真相源；缺省时共享层只能消费 SEO hreflang 同合同投影或当前页面事实兜底，不得自动扩展到全站语言全集
+- 对业务子包来说，正式页面公开面应优先收敛为单个 `page_profile` / `page_config`；`request.state.page_supported_language` 只是共享层从页面合同派生出来的消费态字段，不应倒逼每个子包长期维护第二套独立公开接口
+- 纯 SSR 页面也应产出稳定字段形态；若无需前端增量取词，`client_translation_scopes` 应显式为空集合，而不是依赖运行时隐式缺省
+- 多个页面 runtime 不得在各自路由里长期手写同构的 `request.state` 注入逻辑，应通过共享 helper 统一绑定
+
+回退规则：
+
+- 共享层可在兼容期内从 `page_profile` 推导缺失字段
+- 但该回退只可作为容错，不得继续演化成第二套正式主链
+
+禁止：
+
+- 首屏正文依赖前端请求 `/translations.json` 后再补齐
+- 为了省事把整个模块甚至整站翻译全集内联进 HTML
+- 让 CSR 在首屏阶段重新计算一套独立于 SSR 的 bundle 组合
+- 把页面级翻译请求数量收敛问题，退化为“继续让前端多次串行取词”
+
+推荐结果：
+
+- 对可缓存的 SEO/landing/公开关键词页/博客/帮助页等公开页面，首屏翻译网络请求目标应为 `0`
+- 若存在首屏后额外翻译请求，也只应来自非首屏交互区块或缺词兜底
+
+推荐的稳定装配顺序固定为：
+
+1. `shared bundle`
+2. `page-type bundle`
+3. `page-local override`
+
+正式限制：
+
+- 覆盖层级最多只允许上述三层
+- 不允许 host、页面脚本、模板 helper 在这三层之外再追加第四层覆盖
+
+### 7.3.2 正式优先级表
+
+正式优先级固定如下：
+
+1. `shared bundle`
+2. `page-type bundle`
+3. `page-local override`
+
+语义说明：
+
+- `shared bundle`
+  - 提供共享稳定壳层文案
+  - 不感知单页面特化
+- `page-type bundle`
+  - 提供同类页面通用文案结构
+  - 允许覆盖共享层中被设计为页面可定制的字段
+- `page-local override`
+  - 只允许覆盖白名单字段
+  - 只服务单页面极少量特化
+
+正式要求：
+
+- 同一 key 的正式覆盖链最多经过一次设计性覆盖
+- 如果某 key 同时在多个同层 bundle 中被声明，编译期必须直接报冲突
+- 如果某 key 不在 override 白名单中，`page-local override` 不得覆盖它
+- 不允许在运行时再引入“最后加载者生效”一类隐式优先级
+
+### 7.4 预编译与请求期约束
+
+生产正式要求：
+
+- bundle 解析、profile 解析、dependency 裁决必须在资源编译阶段完成
+- 运行时只允许消费已经进入 `resource manifest` 的编译结果
+- 请求期不允许再次重扫 `locales/`、重建 profile、重做深层 merge
+- 请求期允许的动态行为只应包括：
+  - 按当前语言选择已编译 bundle
+  - 按当前 profile 选择已编译组合结果
+  - 对受控变量做轻量字符串插值
+
+禁止：
+
+- 在请求期根据页面 slug 临时推导第二套 bundle 组合规则
+- 在请求期将多个大 JSON 反复深度 merge 后再输出
+- 将“开发期方便”路径扩散为生产正式路径
+
+### 7.5 缓存与失效策略
+
+生产正式要求：
+
+- 缓存粒度必须围绕正式消费单位设计，至少可稳定定位到：
+  - `owner_app`
+  - `language`
+  - `bundle_id` 或 `profile_id`
+- 缓存失效只能由正式资源版本或正式部署切换触发
+- dev / test / product 的差异只能体现在缓存策略上，不能体现在消费语义上
+
+推荐原则：
+
+- bundle 级缓存优先于页面全集缓存
+- profile 级缓存只缓存编译结果，不缓存运行时隐式推导
+- 若 profile 组合结果可预编译，应优先预编译，而不是在请求期临时拼接
+
+### 7.6 SEO 关键词页扩张规则
+
+本方案必须天然支持 SEO 关键词页扩张，而不引入文案复制和结构失控。
+
+正式要求：
+
+- 新增关键词页时，默认流程应是：
+  1. 新增或调整一个 `composition profile`
+  2. 复用既有 `shared bundle`
+  3. 复用既有 `page-type bundle`
+  4. 只有在确有必要时才新增受限 `page-local override`
+- 不允许把“新增关键词页”默认等价为“复制一整页翻译 JSON”
+- 若多个关键词页出现大面积重复 override，应优先抽回 `page-type bundle`
+
+生产目标：
+
+- 新增 SEO 页面主要靠 profile 组合，而不是复制文案
+- 关键词扩张不应导致翻译体系线性膨胀
+- 关键词业务增长时，翻译体积增长应明显小于页面数量增长
+
+### 7.6.1 profile 最小职责边界
+
+`page_profile` 的正式职责只允许包括：
+
+- 页面身份
+- route 绑定
+- template 绑定
+- bundle 组合
+- 变量注入
+- 页面可暴露语言集合
+- 供 `seo.provider` / `seo.sitemap_provider` 消费的稳定 SEO 输入引用或策略提示
+
+`page_profile` 不允许承担：
+
+- 页面业务逻辑
+- 条件分支执行逻辑
+- 动态内容生成逻辑
+- 第二套 fallback 决策
+- 第二套路由裁决逻辑
+- 直接定义 canonical / hreflang / sitemap / robots 的最终真相
+
+治理原则：
+
+- profile 负责“怎么组合”
+- bundle 负责“内容是什么”
+- override 负责“极少量特化”
+- 任何超出这三者边界的诉求，都应优先回到模板、bundle 或业务代码本身解决
+
+SEO 边界说明：
+
+- `page_profile` 可以携带稳定 SEO 输入，例如 `route_binding`、`template_id`、`seo_profile_ref`、`indexability_hint`
+- `page_supported_language` 是页面语言暴露范围的唯一页面级真相源
+- 对子包或业务 app 的稳定公开面，也应优先只暴露 `page_profile` / `page_config` 解析入口；不要长期并存 `resolve_page_profile(...)` 与 `resolve_page_supported_language(...)` 两套同构公开 surface
+- 页面最终 SEO 输出的正式 owner 仍然是 SEO owner 及其消费的 `seo.provider` / `seo.sitemap_provider`
+- 若项目启用了业务 SEO 子包，则页面生命周期、索引门槛、canonical 收敛、hreflang 暴露、sitemap 成员资格等治理，必须继续由对应 SEO 子包负责
+
+### 7.7 页面 profile 最小示例
+
+以下示例只表达正式结构，不表达具体实现细节。
+
+示例 `page_profile`：
+
+```jsonc
+{
+  "profile_id": "example-topic-landing",
+  "route_binding": "public.topic_landing",
+  "template_id": "topic_landing_v1",
+  "page_supported_language": ["en"],
+  "shared_bundle_ids": [
+    "site_shell.nav",
+    "site_shell.footer"
+  ],
+  "page_type_bundle_ids": [
+    "example_app.topic_landing",
+    "example_app.topic_faq"
+  ],
+  "page_local_override_id": "example-topic-landing",
+  "variables": {
+    "topic": "example topic",
+    "content_type": "guide",
+    "source_context": "example"
+  }
+}
+```
+
+示例 `shared bundle`：
+
+```json
+{
+  "nav": {
+    "home": "Home",
+    "pricing": "Pricing"
+  }
+}
+```
+
+示例 `page-type bundle`：
+
+```json
+{
+  "hero": {
+    "title": "Best {keyword} Translator",
+    "subtitle": "Translate {content_type} from {source_language} instantly."
+  }
+}
+```
+
+示例 `page-local override`：
+
+```json
+{
+  "hero": {
+    "subtitle": "Specialized for Korean comics and webtoon-style layouts."
+  },
+  "seo_copy": {
+    "description": "Translate Korean comics online with high-quality layout support."
+  }
+}
+```
+
+该示例表达的正式意图是：
+
+- 新增关键词页优先新增一个 profile
+- 优先复用共享 bundle 和 page-type bundle
+- 只有在少量文案确需特化时，才启用稀疏 override
+- `page_supported_language = [\"en\"]` 表示该页面只对外暴露英文
+- 其中 `seo_copy` 只表示可被 `seo.provider` 消费的文案输入，不表示页面直接拥有 canonical / hreflang / sitemap 真相
+
+### 7.7.1 模块元信息公开面
+
+当共享运行时仍需要读取“模块元信息”时，这些信息必须优先来自 `pz_page_center` 的页面域运行时投影，而不是继续把页面职责塞回 `locales/config.json` 或业务 app 私有公开面。
+
+正式要求：
+
+- 与页面组合无关、但共享运行时需要读取的模块元信息，仅允许包括这类稳定字段：
+  - `name`
+  - `default_language`
+  - `supported_languages`
+- landing builder、site essentials、business SEO owner 等共享消费者，若确需读取模块元信息，应优先消费 `pz_page_center` 已编译运行时投影
+- `page_profile` 仍只负责页面组合、页面翻译消费声明、页面语言事实投影；不得反向承担模块元信息真相源
+
+迁移约束：
+
+- 在更大范围的模块元数据系统迁移完成前，允许共享层临时保留 `module_config` fallback
+- 该 fallback 只允许作为迁移期兜底，不构成长期正式主链
+- 不允许因为保留 fallback，就重新把 `sections`、`css`、`js`、`session`、`stripe_preconnect` 等页面职责字段放回 `locales/config.json`
+
+## 8. 正式 fallback 规则
+
+fallback 必须唯一且可预测。
+
+建议固定为：
+
+1. 当前 bundle 的当前语言
+2. 当前 bundle 的英文基线
+3. 显式依赖的共享 bundle 的当前语言
+4. 显式依赖的共享 bundle 的英文基线
+
+禁止：
+
+- 跨业务 bundle 任意 fallback
+- 任意 bundle 自动回退到不相关页面的业务文案
+- 通过无限 `base` 兜底掩盖 owner 缺失
+- 通过多层 override 链掩盖 bundle 切分错误
+- 把 fallback 误当作“页面已支持该语言”
+
+说明：
+
+- fallback 只解决“当前已暴露语言页面如何兜底取词”
+- fallback 不得自动创建额外页面语言版本
+- fallback 不得自动把语言加入切换列表、hreflang 或 sitemap
+
+## 9. `base` allowlist 正式规则
+
+`base` 必须进入 allowlist 治理。
+
+框架层定义的是 allowlist 机制，而不是为所有项目硬编码同一组共享文件名。
+
+正式要求：
+
+- 每个 owner app 若声明 `base` 共享面，必须在标准资源元数据中显式列出 allowlist
+- allowlist 必须可被 contract test 和 lint 直接读取
+- allowlist 外的新文件或新前缀必须直接失败
+
+共享站点壳的典型 allowlist 可以包括：
+
+- `nav`
+- `footer`
+- `common`
+
+但这类具体名单属于 app 级治理结果，不是 `pz` 基础层的硬编码常量。
+
+## 10. 分层落位
+
+### 10.1 `pz` 基础层
+
+只有在证明正式合同缺位时，才允许在 `pz` 基础层补以下稳定抽象：
+
+- locale bundle 元信息如何进入 `resource manifest`
+- bundle dependency / fallback policy 的最小合同
+- runtime 只消费 manifest 的正式约束
+
+`pz` 基础层不负责：
+
+- 页面级翻译实现
+- 业务 bundle 列表
+- 业务页面 fallback 细节
+
+### 10.2 官方扩展层 / 共享子包
+
+官方扩展层负责：
+
+- 共享 bundle 的 owner 和资源布局
+- 统一 translation facade 的实现
+- 共享首帧 bundle 的稳定注入策略
+- 共享导航、共享 footer、认证、协议页等共享文案面
+
+共享实现若需要通用 facade，应落在官方扩展层或共享子包，不得回塞 `pz` core。
+
+### 10.3 业务子包
+
+业务子包负责：
+
+- 页面 bundle 真相源
+- 页面依赖哪些共享 bundle
+- 页面使用哪些 composition profile
+- 页面是否存在受限 page-local override
+- 页面级 FAQ / pricing / home / tools 文案
+- 页面级 SEO 文案输入与结构化内容输入，但最终 SEO 输出仍应通过 `seo.provider` / `seo.sitemap_provider` 暴露
+- 页面级 `page_supported_language` 和 `page_language_alternates`，供站点语言切换与 SEO provider 统一消费
+
+### 10.4 宿主项目
+
+宿主只负责：
+
+- 安装哪些 app
+- 调用通用 host builder
+- 不负责发明第二套 i18n 装配规则
+
+## 11. 治理与门禁
+
+长期正式方案必须落成程序化门禁，不能只靠人工约定。
+
+### 11.1 owner lint
+
+必须校验：
+
+- 每个 key 只有一个正式 owner
+- 共享目录中不得出现页面级业务 key
+
+### 11.2 allowlist lint
+
+必须校验：
+
+- `base` 只允许出现 allowlist 文件
+- allowlist 外的新文件或新前缀直接失败
+
+### 11.3 parity contract
+
+必须校验：
+
+- 非英文语言 key 集合与英文基线一致
+- 缺键、重名、owner 冲突都必须显式报错
+
+### 11.4 bundle budget
+
+必须校验：
+
+- 每个 bundle 的体积预算
+- 每个页面 SSR 注入的翻译预算
+- 前端单次加载的翻译预算
+- page-local override 的体积预算
+
+### 11.5 dependency contract
+
+必须校验：
+
+- 页面只能请求自己声明的 bundle
+- 未声明 bundle 的引用直接失败
+- 未出现在 `page_supported_language` 中的语言，不得被页面切换器、hreflang 或 sitemap 暴露
+
+### 11.6 override contract
+
+必须校验：
+
+- override 只能绑定到显式 profile
+- override 只能覆盖白名单字段
+- override 不能成为整页全文案副本
+- 每个 key 的最终来源必须可调试、可追踪
+
+### 11.6.1 override 升级为 bundle 的判定规则
+
+以下情况出现时，必须优先重构为新的 `page-type bundle`，而不是继续扩张 override：
+
+- 多个 profile 重复覆盖同一批字段
+- 同一 override 的字段数量持续增长
+- 同一 override 的体积接近 page-type bundle 规模
+- override 中开始出现结构性文案块，而不是稀疏 patch
+
+正式要求：
+
+- override 是例外能力，不是抽象承载层
+- 当 override 呈现出“可复用模式”时，必须提升为 bundle
+- 治理门禁应能发现这种演化并阻止继续堆积 patch
+
+### 11.7 observability contract
+
+必须校验：
+
+- 运行时能够输出当前页面实际命中的：
+  - profile
+  - bundle 列表
+  - override
+  - 最终语言
+- 每个 key 的最终来源可被调试面或诊断日志追踪
+- 当出现缺键、owner 冲突、非法 override 时，诊断信息必须直接指向正式 owner 和正式资源来源
+
+推荐调试能力：
+
+- 页面级 locale debug surface
+- key source trace
+- 当前响应的翻译 payload 大小统计
+
+### 11.8 performance contract
+
+必须校验：
+
+- 首帧 SSR 注入的翻译体积受预算限制
+- CSR 单次拉取的 bundle 数量和体积受预算限制
+- profile 组合不会把共享 bundle 重复展开为多份大对象
+- 大规模 SEO 页面场景下，新增 profile 不会导致请求期复杂度线性增加
+- 可缓存公开页面不应在首屏渲染路径上依赖前端翻译请求才能形成完整正文
+- 上述页面若仍存在前端首屏翻译请求，必须能明确说明其不是 SEO/public 首屏正文所必需
+
+生产目标：
+
+- 请求期复杂度主要与已编译 bundle 个数相关，而不是与页面总数相关
+- 新增关键词页主要增加静态资源与索引项，不应显著增加请求期 CPU 开销
+
+### 11.8.1 SEO 协同边界：生命周期与内容质量门槛
+
+本规范不单独再定义第二套 SEO 生命周期中心。
+
+正式边界：
+
+- canonical / robots / hreflang / sitemap / structured data 的最终输出，正式 owner 是 SEO owner 与其 provider chain
+- 页面 app 若需要页面级 SEO 真相，必须通过 `seo.provider` / `seo.sitemap_provider` 暴露，而不是让 `page_profile` 直接接管最终 SEO 输出
+- 若项目启用了业务 SEO 子包，则索引门槛、canonical 收敛、sitemap 成员资格、可内链资格、退场动作等治理，应继续由该子包负责
+- 但页面语言暴露范围的唯一页面级真相源，仍应来自 `page_supported_language`
+- 页面语言切换 URL 的唯一真相源来自同一页面合同的 `page_language_alternates`；缺省时只允许消费 SEO hreflang 同合同投影或当前页面事实兜底，不得自动扩展到全站语言全集
+
+`page_profile` 在 SEO 协同中的正式职责仅限于：
+
+- 提供稳定页面身份与 route 绑定
+- 提供模板身份与可复用变量
+- 提供页面级语言事实投影
+- 提供可被 provider 消费的 SEO 输入引用，例如 `seo_profile_ref`、`indexability_hint`
+- 不直接充当 SEO provider 或 sitemap provider
+
+协同约束：
+
+- 仅靠关键词替换、缺乏足够独特内容的页面，不应默认进入可索引状态
+- fallback 比例过高的 locale 页面，不应自动视为可索引页面
+- 若页面长期依赖大体积 override 才成立，应优先判定为 bundle/profile 设计失衡
+- 若项目已有正式 SEO 质量门槛实现，应复用既有门槛，不得在 i18n/profile 层再复制一套判定逻辑
+- 若某页面只支持一个语言，则 hreflang、sitemap 与语言切换器都应只暴露该语言；不得用 `routing.all_supported_languages` 自动扩展当前页面语言切换选项
+
+### 11.9 release acceptance contract
+
+正式上线前至少应满足：
+
+- resource compiler 已能稳定输出 locale bundle / profile / override 的编译结果
+- 首帧 SSR 不再注入整站翻译全集
+- CSR 不再暴露整语言全集加载入口
+- SEO keyword page 的新增流程已验证可通过 profile 组合完成
+- `page_supported_language` / `page_language_alternates` 已被语言切换、`seo.provider`、`seo.sitemap_provider` 一致消费
+- 缺键、owner 冲突、非法 override、非法 dependency 都有明确失败路径
+- 诊断面可以追踪 key 最终来源与 payload 体积
+
+## 12. 迁移策略
+
+### 12.1 第一阶段：冻结扩张
+
+- 停止向 `base` 新增业务页面 key
+- 后续新增翻译必须先判 owner
+
+### 12.2 第二阶段：收敛 `base`
+
+对存量项目，优先收敛那些历史上误落到 `base`、但实际并非共享稳定文案面的目录。
+
+常见类型包括：
+
+- 页面级 SEO
+- 业务 dashboard
+- 业务 share
+
+原则：
+
+- 共享 owner 则迁共享子包
+- 业务 owner 则迁业务子包
+
+### 12.3 第三阶段：引入 bundle 消费
+
+- 页面和前端模块开始按 bundle 读取翻译
+- 停止“整包语言全集”下发
+- page-local override 仅在白名单场景下启用
+
+### 12.4 第四阶段：补齐治理门禁
+
+- allowlist
+- owner lint
+- parity contract
+- bundle budget
+- dependency contract
+- observability contract
+- performance contract
+
+### 12.5 第五阶段：完成存量迁移
+
+在治理门禁到位后，再逐步迁移历史 key 与历史目录。
+
+### 12.6 非兼容声明
+
+本轮长期方案对历史设计的正式态度如下：
+
+- `locales/config.json` 作为历史遗留，本次直接退出正式主链
+- 不保留对 `locales/config.json` 的长期兼容
+- 历史 `base + namespace + 页面整包 JSON` 只视为迁移态，不得继续扩散
+- 新增页面、新增关键词页、新增翻译功能必须遵循新主链，不得再走旧路径
+
+## 13. 反模式清单
+
+以下做法都应视为反模式：
+
+- 把页面组合配置继续塞回 `locales/`
+- 为了省文件数，把整页文案重新塞进单个超大页面 JSON
+- 把 page-local override 当作常规路径使用
+- 让 profile 承担页面业务逻辑或路由分支逻辑
+- 在宿主侧重新拼一套 locale governance 规则
+- 通过运行时多层 merge 解决 bundle 切分不合理问题
+- 遇到重复页面时优先复制文案，而不是抽象 page-type bundle
+
+## 14. 当前结论
+
+长期正式方案应当是：
+
+- 不是继续优化 `base`
+- 不是再造第二套 i18n 资源系统
+- 而是把 i18n 正式收敛成 `pz` 资源体系中的 owner + bundle + manifest + governance 方案
+
+只有这样，才能同时满足：
+
+- `pz` 的单一路径原则
+- 资源 manifest 唯一真相源
+- 最小子包边界
+- 按需取用
+- 生产环境下的长期可治理性