本仓库为 GBA 游戏《火影忍者 RPG》的汉化与发布工程，不包含、不分发任何 ROM 文件。发布形式为：汉化数据 + 与原版 ROM 的 binary diff，配合 HTML 网页 Patcher，由用户在本机使用自有原版 ROM 打补丁得到汉化版。本工程采用 MIT License 开源，详见 LICENSE。
- 不提供 ROM：请自行准备原版《火影忍者 RPG》GBA ROM。
- 补丁方式：提供与原版 ROM 的 binary diff（补丁文件）以及 HTML Patcher 源码/页面。
- 用户流程：在 Patcher 页面 选择本地原版 ROM → 应用补丁 → 下载生成的汉化 ROM。
gba-narutorpg-chs/
├── readme.md # 本文件
├── LICENSE # MIT License
├── hexproj/ # 静态分析：ImHex 工程
│ ├── font_edit.hexproj # 字体/映射等标注（需自备 ROM 并重命名为 font_edit）
│ └── original.hexproj # 原版 ROM 分析用工程（可选）
├── python/ # Python 工具脚本
│ ├── requirements.txt # freetype-py, pillow, click
│ ├── patch.py # 构建汉化 ROM：字模注入 + 译文写回（产出供 differ 生成 diff）
│ ├── differ.py # 生成原版→汉化 ROM 的 diff.json（供网页 Patcher 使用）
│ └── debug/ # 字模、文本导出等脚本
│ ├── 8x8_font.py # TTF → 8×8 GBA 字模
│ ├── 8x16_font.py # TTF → 8×16 GBA 字模
│ ├── text_dumper.py # ROM 文本导出为 JSON（Shift-JIS）
│ └── text_dump/ # 文本导出输出（text_chunk_*.json）
└── patcher/ # HTML Patcher 源码
└── diff.json # 汉化补丁（由 python/differ.py 生成）
| 模块 | 说明 | 状态 |
|---|---|---|
| hexproj | ImHex 工程：ROM 内字体、mapping、二分查找等区域标注，便于分析与手工编辑 | ✅ 已有 |
| python | 构建汉化 ROM（patch.py）与生成 diff.json（differ.py）的流水线；字模/文本导出脚本 | ✅ 就绪 |
| patcher | 网页端 Patcher：用户在本机用 diff.json 对原版 ROM 打补丁得到汉化 ROM（含 ROM 内预制 patch）；在线地址见下方 | ✅ 可用 |
- Python：3.14+，用于汉化构建与 diff 生成（见下方 python 模块）。
- Node/pnpm：用于 Patcher 前端开发与构建（见下方 patcher 模块）。
- ImHex（可选）：用于 ROM 静态分析与字体编辑（见下方 hexproj 模块）。
- 使用 ImHex 打开工程，需在同目录下放置并重命名好的 GBA ROM。
| 工程文件 | 用途 | 所需 ROM 文件名 |
|---|---|---|
| font_edit.hexproj | 字体编辑：字模、mapping、二分查找等标注 | 将 ROM 重命名为 font_edit（或 font_edit.gba） |
| original.hexproj | 原版 ROM 静态分析、阅读与定位 | 将原版 ROM 重命名为 original.gba |
font_edit 使用：ROM 放到 hexproj/，重命名为 font_edit 或 font_edit.gba，用 ImHex 打开 font_edit.hexproj。
original 使用：原版 ROM 重命名为 original.gba，用 ImHex 打开 original.hexproj。
工程内已标注：8×8/8×16 字模与 mapping、迁移后二分查找、新加 8×8 mapping、8×16 映射引用、菜单表与剧情样本等，便于汉化时定位与修改。请使用与本工程对应的 GBA ROM，否则偏移可能不匹配；ROM 需自行准备，仓库不包含任何 ROM。
- 用途：制作汉化数据与 diff，不是用户打补丁用。
patch.py在本地将字模与译文写回 ROM，产出完整汉化 ROM；differ.py比较原版与汉化 ROM，生成 diff.json 供网页 Patcher 使用。
字体（8×8 与 8×16 可指定不同字体，只传一个路径则共用同一字体）：
| 尺寸 | 推荐字体 | 来源与文件 |
|---|---|---|
| 8×8 小字 | Fusion Pixel Font（缝合像素字体） | 使用其 8px 等宽 TTF，如 fusion-pixel-8px-monospaced-zh_hans.ttf |
| 8×16 大字 | MuzaiPixel（目哉像素，k8×12） | 使用 8×12 格 提取字模后 pad 到 8×16（--8x16-scale pad）；字体如 MZPXorig.ttf / MZPXflat.ttf |
依赖：
pip install -r python/requirements.txt # freetype-py, pillow, click常用命令（在仓库根目录执行）：
| 操作 | 命令 |
|---|---|
| 构建汉化 ROM | python python/patch.py 原版.gba 8px字体.ttf 目哉像素.ttf --8x16-scale pad -o 汉化.gba -m font_mapping.json（8×8 用 Fusion Pixel 8px TTF，8×16 用 MuzaiPixel 8×12 提取后 pad 到 8×16；只传一个字体则两种尺寸共用；需已存在 translate/translations.json） |
| 生成 diff.json | python python/differ.py 原版.gba 汉化.gba -o patcher/diff.json |
| 8×8 字模（debug） | python python/debug/8x8_font.py（脚本内配置 font_path、chars） |
| 8×16 字模（debug） | python python/debug/8x16_font.py |
| 文本导出（debug） | python python/debug/text_dumper.py（脚本内配置 ROM_PATH；输出到 python/debug/text_dump） |
字模输出为 .bin 与 _preview.png；文本导出为 text_dump/text_chunk_*.json。
汉化导入流程：从 python/debug/text_dump/ 的 chunk 运行 python python/translate_with_glm.py 可生成/合并 translate/translations.json（需配置 .env 中的智谱 API Key）。patch.py 读取该文件将译文写回 ROM。
直接优化汉化（修改 translate/translations.json）：
- 手工或脚本编辑：直接改
translate/translations.json里对应条目的translation等字段即可生效，下次运行patch.py会使用新译文。编辑时须遵守下方「汉化原则」：长度与original对齐、符号与控制符原样保留。 - 批量重翻部分条目（脚本会合并进现有
translations.json，无需从 text_dump 重新导出全部）：目的 命令 只重翻此前标为「不翻译」的条目 python python/translate_with_glm.py --skiped-only只重翻「原文与译文相同」的条目 python python/translate_with_glm.py --same-only全部重翻 python python/translate_with_glm.py --no-skip仅处理指定 chunk python python/translate_with_glm.py --files text_chunk_001.json仅统计待翻条数 python python/translate_with_glm.py --dry-run调整每批条数 python python/translate_with_glm.py --batch-size 200
完整翻译 prompt 见 python/translate.instruction.md。
- 技术栈：Vite + Vue 3 + TypeScript，UnoCSS，包管理器 pnpm。
- diff.json：汉化补丁，由
python/differ.py生成后放入patcher/diff.json，格式为[{"pos": "0x...", "bytes": [...]}]。
开发与构建：
cd patcher
pnpm install
pnpm dev # 开发
pnpm build # 构建，产物输出到 workspace/pages（供 GitHub Pages 托管）
pnpm preview # 预览构建结果用户打开部署页面或本地 pnpm preview，选择原版 GBA ROM，点击「打补丁并下载」即可；ROM 不上传，全部在浏览器内完成。
修改或生成 translate/translations.json 中的译文时，须遵守以下两点，否则 patch.py 写回 ROM 可能错位或乱码：
- 长度对齐：每条
translation的字符数（Unicode，含空格）必须与对应original完全一致。不足则在译文末尾补空格（全角/半角与原文一致）；过长则压缩表达或删减，最后才考虑删空格。同一句内多段（如菜单多项）时，每段译文字数与该段原文一致，段末用空格补足。 - 符号：原文中的标点、控制符、占位符（如
\n、%d、{name}、♥、…、！等）必须原样保留，不得删改或替换。
- 使用 ImHex 打开
font_edit.hexproj，需在同目录下放置并重命名为font_edit的 GBA ROM。 - 工程内已标注 8×8/8×16 字模、mapping、二分查找函数、菜单与剧情样本等（详见上文「开发方式 → hexproj」）。
- patch.py：校验
translate/translations.json，从 TTF 渲染 8×8/8×16 字模并注入 ROM，写入扩展字符映射，再将汉化文本写回 ROM，产出完整汉化 ROM，供 differ 生成 diff。 - differ.py：比较原版 ROM 与汉化 ROM，生成 diff.json，供 Patcher 网页使用。用户实际打补丁请使用 Patcher 页面。
- debug/：8×8/8×16 字模脚本、
text_dumper.py文本导出（Shift-JIS 扫描，导出为 JSON 分块）。依赖见requirements.txt。
- 在线 Patcher：https://suhli.github.io/gba-narutorpg-chs/
- 用户在本机选择原版 ROM，网页加载 diff.json 对其打补丁，在浏览器内生成汉化 ROM 并下载。补丁内容包含 ROM 内预制修改与字模/译文等汉化数据。
- 纯前端 HTML/JS，无后端、无上传 ROM，所有处理在用户本机完成。
本工程采用 MIT License 开源。
- 本工程仅提供汉化数据与打补丁工具，不提供任何游戏 ROM。
- 请仅对您合法拥有的原版 ROM 进行打补丁；使用与传播 ROM 的责任由用户自行承担。