| name | cangjie-translate |
| description | 将其他语言代码翻译为仓颉语言。支持 ArkTS、Swift、Java、Python 到仓颉的转换,记录翻译经验和等价写法差异 |
| argument-hint | [arkts|swift|java|python] [file-or-code] |
代码翻译为仓颉语言
将 $1 代码翻译为仓颉语言(待翻译内容:$2)。
前置检查(启动翻译前必须完成)
开始翻译前,依次确认以下事项。未确认完毕不要进入翻译流程。
1. 模型能力
参照 base-skill 第 1 步自检。结论影响后续截图辅助流程:
- 多模态 → 可启用"参考截图辅助翻译"
- 纯文本 → 跳过截图,仅依赖源代码翻译
2. 源项目信息
向用户确认(或从参数 / 文件结构自动推断):
| 问题 | 获取方式 | 影响 |
|---|
| 源语言是什么?(ArkTS / Swift / Java / Python) | 参数 $1 或项目 manifest 推断 | 决定资源目录识别和类型映射规则 |
| 源项目路径在哪? | 参数 $2 或用户指定 | 定位源代码和资源 |
| 源项目是否含 UI? | 检查是否有视图/页面/布局文件 | 有 UI → 触发截图辅助和资源迁移 |
3. 目标项目就绪
| 问题 | 检查方式 | 未就绪时 |
|---|
| 仓颉 HarmonyOS 目标项目是否已创建? | 检查 entry/ + module.json5 是否存在 | 需先创建项目骨架 |
目标项目的 entry/src/main/resources/ 目录是否存在? | ls 检查 | 创建资源目录结构 |
4. 截图就绪(仅多模态 + 含 UI 时)
若第 1 步确认为多模态,且第 2 步确认源项目含 UI,向用户询问:
为了更准确还原原项目的视觉与交互,是否希望提供原项目 UI 截图作为参考?
如需提供,请将截图放入 ./translate_refs/ 目录,文件名建议采用 页面名_描述.png。
放置完成后回复"已放置",或直接说"不需要"。
- 用户说"已放置" → 后续流程读取截图辅助
- 用户说"不需要"或目录为空 → 跳过截图辅助
- 纯文本模型 → 不询问,直接跳过
5. 环境配置
翻译完成后需要构建验证,提前确认:
.env 中 DEVECO_HOME 是否已配置?(/build 必需)
- 若未配置,提示用户参照
base-skill 中的平台典型值补充
翻译流程
- 分析源代码的语义和结构
- 复制资源文件 — 见下节"资源文件迁移"(强制,优先于代码翻译)
- 读取参考截图(前置检查已确认截图就绪时)— 见下节"参考截图辅助翻译"
- 查阅
cangjie-kernel skill 确认仓颉语法和 API
- 查阅
cangjie-harmony skill 确认 HarmonyOS 平台 API 的仓颉等价写法
- 若仓颉 / HarmonyOS 无现成等价 API,优先尝试在仓颉侧补齐 helper / adapter / compat 实现,必要时结合互操作桥接;仅在确认无法安全实现时才允许局部跳过
- 逐模块翻译,保持原有逻辑不变
- 翻译完成后查阅
evolution skill 中的已知踩坑记录,避免重复犯错
- 经验回写 — 翻译中遇到的非显而易见问题,按规则写入对应经验目录(见下节"经验回写")
资源文件迁移(强制前置步骤)
原则:翻译代码前,先把原项目的图片、图标、字体、音视频、本地化字符串等资源复制到仓颉工程对应目录。禁止在代码中使用 "placeholder.png"、TODO、占位 URL、或虚构资源名。
识别源项目资源目录
按源语言类型定位:
| 源语言 | 典型资源目录 |
|---|
| ArkTS(HarmonyOS) | entry/src/main/resources/(base/media/、base/element/、rawfile/) |
| Swift(iOS) | Assets.xcassets/、Resources/、*.lproj/、Base.lproj/ |
| Java(Android) | app/src/main/res/(drawable*/、mipmap*/、values*/、raw/、assets/) |
| Python | static/、templates/、assets/、resources/(按框架不同而异,如 Django/Flask/Tkinter) |
映射到仓颉 HarmonyOS 工程
仓颉 HarmonyOS 项目资源放在 entry/src/main/resources/:
| 资源类型 | 目标位置 | 说明 |
|---|
| 位图(png/jpg/webp) | base/media/ | 文件名全小写 + 下划线,如 icon_home.png |
| SVG 矢量图 | base/media/ | 同上,仓颉 ArkUI 支持 svg |
| 颜色/字符串/尺寸 | base/element/color.json、string.json、float.json | 键名小写下划线 |
| 原始音视频/字体 | rawfile/ | 保留原目录结构 |
| 多语言 | zh_CN/element/、en_US/element/ | 与原项目 lproj/values-* 对应 |
| 多分辨率图(iOS @2x/@3x、Android mdpi/hdpi/xhdpi) | 选最高分辨率放入 base/media/ | 鸿蒙按密度自动缩放,无需多份 |
执行步骤
- 枚举源资源:
Glob 列出原项目资源目录下所有文件
- 去重与选优:多分辨率同名文件保留最高清版本;同一资源有多格式时优先 png > jpg > webp
- 重命名:驼峰 / 连字符 → 下划线小写(HarmonyOS 命名规范要求),如
iconHome.png → icon_home.png
- 复制到目标目录:用
Bash(cp ...) 或 Write(二进制文件直接 cp)
- 更新映射表:维护一份"原名 → 新名"映射,翻译代码时按此表替换引用
- string/color 等结构化资源:从源
.strings / .xml / .json 提取键值,合并写入 element/*.json
代码引用方式
仓颉中通过 $r("app.media.icon_home") 或 $rawfile("data.json") 引用资源。翻译时把源代码的资源引用(如 ArkTS 的 $r("app.media.xxx")、Swift 的 UIImage(named:)、Android 的 R.drawable.xxx)统一改写为新的仓颉形式。
禁止项
- ❌ 不要用占位图(如
https://placehold.co/...、纯色方块)
- ❌ 不要写
// TODO: 添加图标
- ❌ 不要引用源项目里不存在的资源名
- ❌ 不要跳过资源迁移直接翻译代码
资源缺失时
如原项目确实没有某资源(如仅在运行时下载),在翻译报告末尾一句话列出:"资源 X 在源项目未找到,需要用户提供",由用户补充。
参考截图辅助翻译
模型能力自检和截图就绪确认已在「前置检查」步骤 1 和步骤 4 中完成。纯文本模型跳过本节。
截图读取流程
前置检查确认用户已将截图放入 translate_refs/ 后:
-
确认截图目录
- 默认路径:
<项目根>/translate_refs/
- 用户可自定义,由用户在回复中说明实际路径
- Claude 不主动创建该目录,仅读取用户已放入的文件
-
读取并使用截图
Glob 列出 translate_refs/**/*.{png,jpg,jpeg,webp} 所有截图
- 依次 Read 每张截图(多模态模型会直接理解图像内容)
- 在翻译时将视觉信息融入决策:
- 控件层次、对齐、间距、圆角等视觉细节
- 颜色、字号、状态差异(默认态/按下态/错误态)
- 截图与代码不一致时,以代码语义为准,但可在注释或报告中标注"视觉差异:<描述>"供用户确认
-
跳过条件(任一即跳过):前置检查确认为纯文本、translate_refs/ 不存在或为空、用户明确不需要
注意事项
- 截图仅作辅助,不替代源代码分析;源代码不存在的逻辑不要臆造
- 不把截图内容写入代码注释(占空间且无意义),仅用于形成翻译决策
- 翻译完成后,若发现源码与截图有明显偏差,在最终交付说明中一句话列出差异,让用户决定是否调整
功能完整度约束(强制)
目标:尽可能翻译全部功能。不要因为仓颉或 HarmonyOS 没有现成 API,就直接删掉页面逻辑、交互、状态、校验、动画、异步流程或业务分支。
遇到"仓颉没有现成 API / 组件 / 语法糖"时,按以下顺序处理:
- 先确认是否真的缺失:查
cangjie-kernel、cangjie-harmony、已有经验文档,确认是否已有等价能力或可组合实现
- 优先自行补齐:在当前项目内补充最小可用实现,例如 helper、adapter、compat 层、扩展函数、工具类、简单组件封装
- 必要时做桥接:若仓颉侧无直接封装,但底层 HarmonyOS / ArkTS 能力可用,可通过互操作或薄封装桥接实现,前提是不破坏项目整体结构
- 最后才允许跳过:只有在确认无法安全实现、或实现成本显著超出当前翻译边界时,才允许跳过局部功能
跳过规则:
- 只允许跳过无法实现的最小局部功能点,不要因为一个 API 缺失就删除整个模块
- 必须在最终翻译报告中列出:跳过的功能点、影响范围、已尝试方案、无法实现的原因、后续建议
- 禁止用虚构 API、空函数、直接返回默认值、硬编码假数据来伪装"已实现"
- 若可以做功能降级,优先保留核心可用性,再在报告中说明与原实现的差异
翻译规则
- 功能完整度:遵循上节约束(先确认→补齐→桥接→最后才跳过)
- 保持代码语义等价,不额外添加功能
- 使用仓颉惯用写法,不要逐行直译
- 类型映射优先查阅对应子目录下的经验文档(如有)
- 翻译后代码应可直接编译,注意仓颉与源语言的关键差异
经验回写(翻译完成后强制执行)
翻译过程中解决了非显而易见的问题后,必须将经验写入对应位置。
回写时机
- 每完成一个模块的翻译并编译通过后,立即回写该模块中遇到的问题
- 不要等全部翻译完才一次性回写,避免遗漏细节
回写规则
| 经验类型 | 写入位置 | 示例 |
|---|
| 源语言 → 仓颉的语法/表达差异 | cangjie-translate/<lang>2cangjie/ | 类型映射、API 等价写法、语法糖替代 |
| 仓颉语言通用问题(与翻译无关) | evolution/cangjie/ | 编译器行为、宏约束、标准库陷阱 |
判定规则:若问题是"从某语言翻译到仓颉时才会遇到",写入 *2cangjie/;若问题是"用仓颉开发都会遇到",写入 evolution/cangjie/。
经验目录
按源语言记录到对应子目录:
每个子目录下按需创建主题文件(如 types.md、ui.md、async.md),并在子目录的 README.md 中维护索引。
格式
遵循 evolution/SKILL.md 中的"单条经验格式":问题现象 → 原因 → 解决方案 → 相关文档。