ZUI 扩展库国际化

准备

按 共享工作流 解析本次所需上下文、读取适用规则并检查所有权；已有且未变化的发现直接复用。阅读 i18n 规范 中与本次修改有关的部分。

阅读目标语言键、占位符和消费路径；新增接线或改变覆盖/回退行为时再检查相关入口、类型、基础设施及必要参考。宿主运行时验收需要已确认的宿主，不根据历史快照猜测 API。

目标采用带命名空间的全局注册，或需要借鉴此类接入方式时，按需阅读 禅道全局 i18n 模式参考。其中的 namespace、语言文件组织和加载顺序是可复用的项目约定；是否采用以目标项目契约为准，不用于强制迁移已有模式。

盘点与模式

按请求确定语言、键或接线范围；整库审计才遍历整库，局部修订只追踪受影响内容。

1. 枚举目标范围内所有用户可见字符串及其消费路径，包括标签、按钮、标题、placeholder、提示、可见错误和 schema 文案；排除协议值、事件名、CSS 类、icon、字段 key/name、注释与仅开发日志。
2. 盘点现有语言目录、注册入口、实际加载路径、三语言键结构、占位符、源码键引用、硬编码残留、实例覆盖与 fallback 行为。
3. 选择模式：
   • audit：用户只要求检查时保持只读，输出证据和建议；
   • bootstrap：没有 i18n 基础时建立当前扩展项目适用的最小结构；
   • complete：保留现有结构，补齐缺失语言、键、引用或加载；
   • clean：均符合当前契约时不制造无意义改动。
4. 按共享工作流先检查请求、已确认决定和目标现状，合理沿用既有约定；仅有无法可靠消除且会实质改变国际化目标、公开契约或交付边界的歧义时询问，否则直接在本领域内实施，不增加确认门禁。

实施

按本次涉及的文案或接线应用以下约束，保留未变化的结构和契约：

1. 判断组件静态 i18n 映射、带命名空间的全局注册或目标项目已有等价机制。组件私有文案不无理由进入全局空间；全局 namespace 必须稳定且与其他扩展和内置库不冲突。
2. namespace 优先沿用公开兼容契约；新建时结合真实 packageName、zuiName、宿主注册结果和扩展项目惯例设计并记录，禁止硬编码某个项目 scope 或只把 folderName 转 camelCase 就视为充分证据。
3. 新接入时默认按当前 ZUI 规范提供 zh_cn、zh_tw、en，但若扩展项目明确采用其他文件名或语言集合，服从其契约并说明兼容映射。以 typeof、satisfies 或共享类型保证所有语言键和嵌套结构一致。
4. 确保入口或真实消费路径加载语言注册。Preact + vanilla 组合要验证 ComponentFromReact 的静态映射和实例 options/props 覆盖路径。
5. 组件实现调用 getLang 时只传翻译键，如 getLang('group.key')，有插值时才传对象参数，如 getLang('error.notFound', {name})；不在调用处传入或拼接中文等回退文案。基础文案维护在语言资源中，需要的回退统一由 i18n 配置或库级 helper 处理。所有语言保留相同占位符；区分 ZUI i18n 插值与下游组件稍后处理的模板占位符，避免提前消费。
6. 明确并验证全局语言、实例 lang、实例 i18n 覆盖、缺失键默认值、不支持语言和语言码归一化。不要承诺当前源码没有实现的 fallback 链。
7. 动态切换语言时区分 render 内求值与模块级常量一次性求值；需要实时更新时设计可重新求值的数据路径，不让静态常量伪装成响应式。
8. 只修改 targetLibRoot 内国际化所需源码、类型与接线。依赖、lint、类型和测试从 extensionRoot 执行；不修改宿主源码、依赖、lockfile 或注册；宿主生成物和缓存写入遵循共享工作流的验证隔离与批准规则。
9. 文档、调试页和无关运行时 API 仅在用户请求或共享批准范围明确包含时修改，并按需读取对应技能，复用已有上下文和批准。

验证与交付

按共享工作流验证本次涉及的语言键、嵌套、占位符、类型或接线，完成范围内修复和复验。新增语言或改变加载、实例覆盖、回退和动态行为时，补充相应真实消费路径检查。

涉及宿主运行时或分发时，再通过已确认的 zuiRoot + extsName 和准确 zuiName 做所需联合构建或交互验证；执行位置及服务管理遵循共享规则。

作为子流程时只处理共享范围内的 i18n 工作。交付时报告模式、namespace、键与接线变化、分层验证结果和待决术语，不自动提交、推送或发布。