Pixel-Composer-Chinese-Localization

Imported from LifeOfAc/Pixel-Composer-Chinese-Localization (AGENTS.md). Install upstream with npx skills add LifeOfAc/Pixel-Composer-Chinese-Localization. Copyright stays with the author.

Pixel Composer 汉化工程 - OpenCode 工作指南

交互要求

• Thinking思考过程用中文表述
• Reply回答也要用中文回复

一、项目结构

Pixel-Composer-Chinese-Localization/
├── en/                        # 英文源文件（gitignore忽略，不纳入版本控制）
│   ├── config.json
│   ├── fonts/
│   ├── junctions.json
│   ├── nodes.json
│   ├── notes/
│   └── words.json
├── zh/                        # 中文翻译文件（主要工作目录）
│   ├── config.json            # 翻译配置
│   ├── fonts/fonts.json       # 字体配置
│   ├── junctions.json         # 节点参数引用说明
│   ├── nodes.json             # 节点定义翻译（嵌套结构）
│   ├── notes/                 # 参考文档翻译
│   └── words.json             # 界面词库翻译（扁平键值对）
├── Nodes/                     # 本地节点文件翻译（Actions等）
├── Welcome files/             # 汉化教程文件
├── 辅助工具/                   # 辅助脚本工具
├── 一键汉化工具/               # 一键安装器
└── 历史版本存档/               # 旧版汉化归档

需要翻译的文件类型

1. 界面词库文件 (words.json)

格式：扁平键值对 {"key": "中文翻译"}

作用：菜单、按钮、对话框、节点分类名等UI文本

特点：无嵌套结构，key为英文snake_case

示例：

{
  "save": "保存",
  "cancel": "取消",
  "add_node": "添加节点"
}

2. 节点定义文件 (nodes.json)

格式：嵌套JSON，每个节点包含：

• name: 节点显示名称
• tooltip: 节点功能说明（可选）
• inputs: 输入参数数组
• outputs: 输出参数数组（可选）

参数对象结构：

• name: 参数名（必须翻译）
• tooltip: 参数提示（可选，有则翻译）
• display_data: 下拉选项数组（可选，含 -1.0 分隔符，有则翻译）

示例：

"Node_2D_Light": {
  "name": "2D光源",
  "tooltip": "在图像上应用不同形状的光源。",
  "inputs": [
    { "name": "输入面" },
    { "name": "光源形状", "display_data": ["点光源", "椭圆光", -1.0, "线光源"] },
    { "name": "衰减方式", "tooltip": "控制光源随距离衰减的方式。" }
  ],
  "outputs": [
    { "name": "输出面" }
  ]
}

3. 连接点引用文件 (junctions.json)

格式：节点ID -> 参数名 -> 引用备注 的嵌套映射

作用：标记特定节点参数需要的额外参考文档

4. 本地节点文件 (Nodes/ 目录)

格式：单个JSON文件，对应 %LOCALAPPDATA%/PixelComposer/Nodes 下的节点

目前主要翻译 Actions/ 下的节点。

二、汉化核心原则

界面词库翻译策略

中文编程函数命名法（"到"字结构）

类型转换统一用"到"字结构：

• 无前置类型 = Variant（变体/通用型），直接"到结果"
• 有前置类型 = 专用型，"类型到结果"

排序逻辑：

• 到文本、到数值 ← 通用，排最前
• 颜色到文本、二维到文本 ← 专用，排后面

设计优势：搜索"到"先看到通用函数；搜索"颜色"能命中专用函数。

动宾结构

动作类词汇用动词+名词的动宾结构，省略冗余介词：

• Load File → 加载文件（非"加载一个文件"）
• Save Project → 保存项目

状态/属性类

名词/形容词类词汇直接标签化：

• Active → 启用
• Visible → 可见

术语一致性映射表（必须遵守）

三、节点文件汉化规范

节点名称翻译

格式：Node_英文域名_功能名 → 中文功能名

命名规则：

1. 保留技术前缀（MK/VFX/3D/2D等）作为标识
2. 核心功能意译
3. 避免过度翻译软件特有名词

示例：

"Node_Blur_Bokeh": "散景模糊",
"Node_3D_Camera": "3D摄像机",
"Node_MK_Fall": "MK落叶",
"Node_VFX_Spawner": "VFX生成器",
"Node_Tunnel_In": "隧道发送器",
"Node_Tunnel_Out": "隧道接收器",
"Node_3D_Displace": "3D置换"

参数名翻译

核心原则：参数名 = 属性标签，不是句子

下拉选项(display_data)翻译

原则：选项是用户选择值，必须简短明确。保留 -1.0 分隔符不变。

// 混合模式
["正常", "替换", -1.0, "正片叠底", "颜色加深", "线性加深", "最小", -1.0, "相加", "滤色"]

// 动画结束行为
["循环", "往返", "销毁"]

// 分布类型
["均匀", "随机", "泊松"]

// 过采样模式
["空白", "钳制", "重复"]

// 光源形状
["点光源", "椭圆光", "线光源", "非对称线光", "光剑", "聚光灯", "火焰光"]

Tooltip翻译

原则：解释功能，不是字面翻译。Tooltip有则翻译，无则保留不添加。

// 正确（功能解释）
"Frames delay between each particle spawn."
→ "每次生成粒子之间的帧延迟。"

// 正确
"Make the particle rotates to follow its movement."
→ "使粒子旋转跟随其运动方向。"

四、汉化工作流程

步骤1：读取项目文件

1. 以 zh/ 目录为主要工作目录
2. 识别目标文件：words.json / nodes.json / junctions.json / Nodes/ 下文件
3. 如需参考英文原文，可读取 en/ 下的对应文件（en目录gitignore忽略）

步骤2：建立上下文

1. 读取 zh/ 下已有翻译文件作为参考
2. 对照 en/ 下的英文原文确认术语
3. 识别未翻译项或需要润色的翻译

步骤3：执行翻译

words.json：

• 先识别类型转换类（含 to/convert 语义）→ 用"到"字结构
• 再识别动作类（动词开头）→ 动宾结构
• 最后识别状态/属性类（名词/形容词）→ 简洁标签化

nodes.json：

• 节点名：前缀保留 + 功能意译
• 参数名：参考术语映射表，确保跨节点一致
• 选项值：参考现有翻译保持一致
• tooltip：有则翻译，无则保留不添加

步骤4：一致性检查

1. 同一英文术语全文统一（如 "Surface In" 在所有节点中都译为"输入面"）
2. -1.0 分隔符在 display_data 中必须保留
3. JSON格式合法（无尾随逗号）
4. 文件编码为UTF-8

步骤5：验证

检查项：

• 所有翻译项无遗漏
• display_data 中的 -1.0 分隔符已保留
• 节点名无遗漏
• 参数名无遗漏
• tooltip有则翻译，无则保留null/缺失
• 同一术语全文一致
• JSON格式合法
• 文件编码为UTF-8

五、自建词库维护

翻译过程中如遇到新术语，应在 zh/ 下维护以下自建词库文件：

界面词库 (words_dictionary.json)

按功能分类存储UI词汇翻译：

{
  "general": { "terms": { "save": "保存", "load": "加载" } },
  "view": { "terms": { "zoom_in": "放大", "zoom_out": "缩小" } },
  "nodes": { "terms": { "add_node": "添加节点", "remove_node": "移除节点" } },
  "types": { "terms": { "to_text": "到文本", "to_number": "到数值" } }
}

节点参数词库 (node_params_dictionary.json)

按节点类型分类存储参数翻译：

{
  "common_params": { "terms": { "Surface In": "输入面", "Mask": "遮罩" } },
  "particle_params": { "terms": { "Spawn Delay": "生成延迟", "Lifespan": "生命周期" } },
  "blur_params": { "terms": { "Strength Map": "强度贴图", "Iteration": "迭代" } }
}

选项词库 (options_dictionary.json)

{
  "blend_modes": { "terms": ["正常", "正片叠底", "相加", "滤色"] },
  "loop_modes": { "terms": ["循环", "往返", "销毁"] },
  "spawn_types": { "terms": ["持续流", "爆发", "触发"] }
}

六、质量要求

1. 一致性优先：同一术语全文必须统一，不可出现"输入面"/"表面输入"混用
2. 中文标点：中文文本用全角标点，英文缩写和文件扩展名保留半角
3. 保留原分隔符：display_data 中的 -1.0 分隔符不可删除或修改
4. 不新增内容：英文原文没有的 tooltip 不添加，不擅自扩充翻译范围
5. 不做意译过度的润色：技术术语保持精确，功能说明保持简洁

七、注意事项

• en/ 目录已被 .gitignore 忽略，仅作本地参考，不纳入版本控制
• 版本号如 1.20.0.10 代表基于该版本的Pixel Composer进行的汉化
• Nodes/ 下的节点文件对应的是 %LOCALAPPDATA%/PixelComposer/Nodes 的本地节点
• junctions.json 不直接翻译，而是用于标记需要跳转参考文档的参数
• config.json 中的 per_character_line_break: true 是中文换行配置，不应修改