# Zuix I18N

> 审计或实现独立 ZUI 扩展库的文案、语言接线及覆盖和回退行为。需求明确时直接实施；只要求审计时保持只读。

- Skill: `easysoft/zuix-i18n` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add easysoft/zuix-i18n`
- Raw SKILL.md: https://api.skillmd.com/api/skills/easysoft/zuix-i18n/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: easysoft (https://skillmd.com/u/easysoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/easysoft/zuix-i18n

---


# ZUI 扩展库国际化

## 准备

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

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

目标采用带命名空间的全局注册，或需要借鉴此类接入方式时，按需阅读 [禅道全局 i18n 模式参考](references/zentao-global-i18n.md)。其中的 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、键与接线变化、分层验证结果和待决术语，不自动提交、推送或发布。