cangjie-translate

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 中的平台典型值补充

翻译流程

1. 分析源代码的语义和结构
2. 复制资源文件 — 见下节"资源文件迁移"（强制，优先于代码翻译）
3. 读取参考截图（前置检查已确认截图就绪时）— 见下节"参考截图辅助翻译"
4. 查阅 cangjie-kernel skill 确认仓颉语法和 API
5. 查阅 cangjie-harmony skill 确认 HarmonyOS 平台 API 的仓颉等价写法
6. 若仓颉 / HarmonyOS 无现成等价 API，优先尝试在仓颉侧补齐 helper / adapter / compat 实现，必要时结合互操作桥接；仅在确认无法安全实现时才允许局部跳过
7. 逐模块翻译，保持原有逻辑不变
8. 翻译完成后查阅 evolution skill 中的已知踩坑记录，避免重复犯错
9. 经验回写 — 翻译中遇到的非显而易见问题，按规则写入对应经验目录（见下节"经验回写"）

资源文件迁移（强制前置步骤）

原则：翻译代码前，先把原项目的图片、图标、字体、音视频、本地化字符串等资源复制到仓颉工程对应目录。禁止在代码中使用 "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/	鸿蒙按密度自动缩放，无需多份

执行步骤

1. 枚举源资源：Glob 列出原项目资源目录下所有文件
2. 去重与选优：多分辨率同名文件保留最高清版本；同一资源有多格式时优先 png > jpg > webp
3. 重命名：驼峰 / 连字符 → 下划线小写（HarmonyOS 命名规范要求），如 iconHome.png → icon_home.png
4. 复制到目标目录：用 Bash(cp ...) 或 Write（二进制文件直接 cp）
5. 更新映射表：维护一份"原名 → 新名"映射，翻译代码时按此表替换引用
6. 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/ 后：

1. 确认截图目录

   • 默认路径：<项目根>/translate_refs/
   • 用户可自定义，由用户在回复中说明实际路径
   • Claude 不主动创建该目录，仅读取用户已放入的文件

2. 读取并使用截图

   • Glob 列出 translate_refs/**/*.{png,jpg,jpeg,webp} 所有截图
   • 依次 Read 每张截图（多模态模型会直接理解图像内容）
   • 在翻译时将视觉信息融入决策：
     • 控件层次、对齐、间距、圆角等视觉细节
     • 颜色、字号、状态差异（默认态/按下态/错误态）
     • 截图与代码不一致时，以代码语义为准，但可在注释或报告中标注"视觉差异：<描述>"供用户确认

3. 跳过条件（任一即跳过）：前置检查确认为纯文本、translate_refs/ 不存在或为空、用户明确不需要

注意事项

• 截图仅作辅助，不替代源代码分析；源代码不存在的逻辑不要臆造
• 不把截图内容写入代码注释（占空间且无意义），仅用于形成翻译决策
• 翻译完成后，若发现源码与截图有明显偏差，在最终交付说明中一句话列出差异，让用户决定是否调整

功能完整度约束（强制）

目标：尽可能翻译全部功能。不要因为仓颉或 HarmonyOS 没有现成 API，就直接删掉页面逻辑、交互、状态、校验、动画、异步流程或业务分支。

遇到"仓颉没有现成 API / 组件 / 语法糖"时，按以下顺序处理：

1. 先确认是否真的缺失：查 cangjie-kernel、cangjie-harmony、已有经验文档，确认是否已有等价能力或可组合实现
2. 优先自行补齐：在当前项目内补充最小可用实现，例如 helper、adapter、compat 层、扩展函数、工具类、简单组件封装
3. 必要时做桥接：若仓颉侧无直接封装，但底层 HarmonyOS / ArkTS 能力可用，可通过互操作或薄封装桥接实现，前提是不破坏项目整体结构
4. 最后才允许跳过：只有在确认无法安全实现、或实现成本显著超出当前翻译边界时，才允许跳过局部功能

跳过规则：

• 只允许跳过无法实现的最小局部功能点，不要因为一个 API 缺失就删除整个模块
• 必须在最终翻译报告中列出：跳过的功能点、影响范围、已尝试方案、无法实现的原因、后续建议
• 禁止用虚构 API、空函数、直接返回默认值、硬编码假数据来伪装"已实现"
• 若可以做功能降级，优先保留核心可用性，再在报告中说明与原实现的差异

翻译规则

• 功能完整度：遵循上节约束（先确认→补齐→桥接→最后才跳过）
• 保持代码语义等价，不额外添加功能
• 使用仓颉惯用写法，不要逐行直译
• 类型映射优先查阅对应子目录下的经验文档（如有）
• 翻译后代码应可直接编译，注意仓颉与源语言的关键差异

经验回写（翻译完成后强制执行）

翻译过程中解决了非显而易见的问题后，必须将经验写入对应位置。

回写时机

• 每完成一个模块的翻译并编译通过后，立即回写该模块中遇到的问题
• 不要等全部翻译完才一次性回写，避免遗漏细节

回写规则

经验类型	写入位置	示例
源语言 → 仓颉的语法/表达差异	cangjie-translate/<lang>2cangjie/	类型映射、API 等价写法、语法糖替代
仓颉语言通用问题（与翻译无关）	evolution/cangjie/	编译器行为、宏约束、标准库陷阱

判定规则：若问题是"从某语言翻译到仓颉时才会遇到"，写入 *2cangjie/；若问题是"用仓颉开发都会遇到"，写入 evolution/cangjie/。

经验目录

按源语言记录到对应子目录：

• ArkTS → 仓颉：arkts2cangjie/
• Swift → 仓颉：swift2cangjie/
• Java → 仓颉：java2cangjie/
• Python → 仓颉：python2cangjie/

每个子目录下按需创建主题文件（如 types.md、ui.md、async.md），并在子目录的 README.md 中维护索引。

格式

遵循 evolution/SKILL.md 中的"单条经验格式"：问题现象 → 原因 → 解决方案 → 相关文档。