renpy-toolkit 1.0.0 — 插件 / agent skill（首推）

renpy-toolkit 1.0.0 — 发布说明 / Release Notes

面向 Ren'Py 游戏的汉化与制作辅助工具包。核心能力是从零生成完整的汉化骨架——
包括只有 .rpyc、拿不到源码的发行版。

A toolkit for Ren'Py authoring and localization. Its core capability is generating a
complete translation skeleton from scratch, including for releases that ship only
.rpyc files with no sources at all.

---

中文

这个版本解决什么

官方 renpy <游戏> translate <语言> 只遍历磁盘上的 .rpy 文件，所以对「作者只发了
.rpyc」的成品游戏产不出任何骨架——而这恰恰是汉化最常遇到的形态。

本工具改成运行游戏本身，从引擎内存里读 translator.file_translates 与 SL2 屏幕树，
因此不依赖源码。在一份 50 个 .rpyc 的发行版上实测：

指标	结果
对白块	58,249（引擎自带 lint 对原文与译文报的是同一个数字）
字符串	约 2,700 条（界面文字、show text、菜单选项等）
耗时	19.6 秒
覆盖率	与一份已上线成品译料对比，唯一原文串覆盖 93.0%

三条独立的发行线

三份产物各自独立：exe 不依赖插件与 skill，插件与 skill 也不含、不调用 exe。

线	适合	怎么用
插件 / pip	有 Python、想留在命令行	pip install renpy-toolkit（含 Excel/字体装 [all]）；或解压便携 zip 跑 renpy-toolkit.cmd
Agent skill	给 AI 助手用	把 skills/renpy-toolkit/ 放进 skill 目录
Windows exe（已停止维护）	只想点按钮，不碰命令行	解压 zip，放到游戏文件夹旁边，双击 renpy-toolkit.exe

首推插件与 agent skill 两条线：它们是本项目的主线，随版本更新、有支持、跨平台；
exe 只是「不想碰命令行」的一次性便利形态，已停止维护。

各有各的分工，也各有各的局限

线	分工	局限
插件 / pip（首推）	全部功能的唯一落点，也是唯一持续更新的线	需要 Python 3.8+（或用便携 zip 自带运行时）；tl gen 必须由目标游戏自带的 lib/py3-*/python.exe 来跑，工具自身无法替代
agent skill（首推·AI 场景）	不含代码，只把同一套命令与判断教给 AI 助手	能力上限等于插件：本机没有工具包就跑不动；拷走 skill 目录时 scripts/rptk.py 必须能定位 plugin/dsh-renpy-toolkit，或设 RPTK_HOME
Windows exe（已停止维护）	图形壳，功能与插件相同，不再新增	仅 Windows；界面借系统浏览器，个别机器上 Edge 自己的「无法更新」页会挡住界面（改用 --tab）；受限账户下引导器可能建不了解包临时目录（需 --runtime-tmpdir 重打包）；不参与后续修复

exe 的下载在单独的 Release：exe-v1.0.0。（本页只挂插件与 skill 两份产物。）

（已停止维护） exe 发行线已停止维护，不再随新版本发布。exe-v1.0.0 里的包已更新为
最后一次修复版（浅色高对比界面、全部按钮可用），之后不再变动。插件与 skill 两条线不受影响。

主要能力

生成骨架 tl gen 跑游戏本体，一次抓齐对白与界面文本。骨架用原文占位而不是
空串——引擎里 new "" 是「有效译文」，会把界面文字整片擦成空白。

没有源码也能读 decompile 用白名单 pickle 虚拟机还原 .rpyc，不执行游戏的字节码；
rpa 读写 RPA-2.0/3.0 归档，支持非默认 key，目录里有两个 archive.rpa 也能一起读。

译文质量 verify 检查覆盖率、标签配对、插值、空译文、结巴丢失等；port 在游戏
更新后按标识符把旧译本搬到新骨架；glossary 用术语表检查译名统一。

三类「翻不了」的文本 跨屏多义 → tl context 生成消歧补丁；变量拼接
（f"You bought {n} {item}!"）→ tl untranslatable 列出、tl fix-fstrings 给方案；
硬编码字体 → font map 生成 translate <lang> python: 替换块、font check 查缺字。

改文件不怕改坏 每次写盘前自动留副本（.bak）或 Git 快照
（--backup-mode git），tl backup list/restore 可逐次回退；机器上没有 git 时自动
降级为 .bak 并明确提示。

exe 形态的两点说明（已停止维护）

界面是「本地小服务 + 系统浏览器窗口」，不需要 WebView2；启动后自动扫描 exe 所在目录
及其一级子目录里的 Ren'Py 游戏，弹窗让你选一个（0 个、1 个、多个都会弹）。

除「生成汉化骨架」写进 game\tl\<语言>\ 之外，其余产物都收在 exe 旁边的
renpy-toolkit-数据\（日志、导出表格、反编译结果、备份快照、临时文件），不会在游戏
目录里留东西。

已知限制

• tl gen 需要游戏自带的解释器（lib/py3-*/python.exe）——骨架必须由目标游戏的运行时给出。
• 单文件 exe 每次启动会解包到系统临时目录；若机器策略禁止创建该目录，可用
  --runtime-tmpdir <可写目录> 重新打包，或改用一键包形态。
• Git 快照需要 git 2.15+；没有时自动降级为 .bak。
• 只提供 Windows exe；Python 形态在三大平台都可运行。

许可

MIT。上游参考：renpy/renpy、
CensoredUsername/unrpyc、
Dclef/renpy-tl、
ZYKsslm/RenPy-Tutorial、
Shizmob/rpatool。没有 import 它们的代码，
规则依据各自在 docs/ 里逐条标注。

---

English

What this release solves

The official renpy <game> translate <lang> command only walks .rpy files present on
disk, so for a finished game that ships only .rpyc it produces no skeleton at
all — which is exactly the case most localizations run into.

This toolkit instead runs the game's own runtime and reads
translator.file_translates plus the SL2 screen tree from engine memory, so it does not
need sources. Measured on a release with 50 .rpyc files:

Metric	Result
Dialogue blocks	58,249 (the engine's own lint reports the same figure for source and translation)
Strings	~2,700 (UI labels, show text payloads, menu options)
Duration	19.6 s
Coverage	93.0% of unique source strings, compared against a shipping translation

Three independent release lines

The three artifacts stand alone: the exe does not depend on the plugin or the skill,
and neither of them contains or invokes the exe.

Line	For	Start with
Plugin / pip	Python available, prefer the CLI	pip install renpy-toolkit ([all] adds Excel and font support); or unzip the portable zip and run renpy-toolkit.cmd
Agent skill	AI assistants	Drop skills/renpy-toolkit/ into the skills directory
Windows exe (DEPRECATED)	Clicking buttons, no command line	Unzip beside the game folder, double-click renpy-toolkit.exe

The plugin and the agent skill are the two lines we recommend. They are the main
line: maintained, supported, cross-platform. The exe is a one-off convenience shell for
people who will not touch a command line, and it is no longer maintained.

What each line is for, and what it cannot do

Line	Role	Limits
Plugin / pip (recommended)	Where every feature lives; the only line that keeps receiving updates	Needs Python 3.8+ (or the runtime bundled in the portable zip); tl gen must run on the target game's own lib/py3-*/python.exe
agent skill (recommended for AI use)	No code — it teaches an AI assistant the same commands and judgement	Its ceiling is the plugin: with no toolkit on the machine it cannot run; if you copy the skill away, scripts/rptk.py must still locate plugin/dsh-renpy-toolkit, or set RPTK_HOME
Windows exe (DEPRECATED)	A GUI shell with the same features, frozen, no longer extended	Windows only; the UI borrows your system browser and on some machines Edge's own "can't update" page covers it (use --tab); on restricted accounts the bootloader may fail to create its unpack directory (rebuild with --runtime-tmpdir); receives no further fixes

The exe is published as a separate release: exe-v1.0.0. This page carries only
the plugin and skill artifacts.

DEPRECATED. The exe release line is no longer maintained and receives no new
releases. The package in exe-v1.0.0 has been updated to the final fixed build
(light high-contrast UI, every button working) and will not change again. The
plugin and skill lines are unaffected.

Capabilities

Skeleton generation — tl gen runs the game itself and captures both dialogue and UI
text in one pass. Bodies use the source text as the placeholder, never "": in the
engine new "" is a valid translation and renders text as blank.

Works without sources — decompile restores .rpyc through a whitelisting pickle
VM and never executes game bytecode; rpa reads and writes RPA-2.0/3.0 archives,
supports non-default keys, and reads both archive.rpa and archive2.rpa in one go.

Translation quality — verify checks coverage, tag balance, interpolation, empty
targets and lost stutters; port carries old translations into a new skeleton by
identifier after a game update; glossary checks terminology consistency.

Three kinds of untranslatable text — same string on different screens →
tl context emits a disambiguation patch; f-strings (f"You bought {n} {item}!") →
tl untranslatable lists them and tl fix-fstrings proposes a fix; hard-coded fonts →
font map emits a translate <lang> python: block and font check reports missing
glyphs.

Safe writes — every write keeps the previous bytes as a .bak copy or a Git
snapshot (--backup-mode git), with tl backup list/restore to step back; without git
installed the git mode degrades to .bak and says so.

About the exe (DEPRECATED)

The window is a local HTTP service plus your system browser in --app mode — no
WebView2 required. On start it scans the exe's folder and one level below, and always
shows a picker (zero, one or many games).

Only the skeleton is written into the game (game\tl\<language>\). Everything else —
logs, exported spreadsheets, decompiled scripts, snapshots, scratch files — lands in
renpy-toolkit-数据\ beside the exe.

Known limitations

• tl gen needs the game's own interpreter (lib/py3-*/python.exe); the skeleton must
  come from the target game's runtime.
• The single-file exe unpacks into the system temp directory on each start. If machine
  policy blocks that, rebuild with --runtime-tmpdir <writable dir> or use the portable
  zip instead.
• Git snapshots need git 2.15+; without it the mode degrades to .bak.
• The exe is Windows-only; the Python forms run on any platform.

License

MIT. Upstream references: renpy/renpy,
CensoredUsername/unrpyc,
Dclef/renpy-tl,
ZYKsslm/RenPy-Tutorial,
Shizmob/rpatool. No upstream code is imported;
each rule is cited in docs/.

renpy-toolkit Windows exe 1.0.0 — 一键包（最后一版，已停止维护）

renpy-toolkit Windows exe 1.0.0 — 一键包（最后一版，已停止维护）

先把话说清楚：本项目首推「插件 / pip」与「agent skill」两条线。
它们随版本更新、有支持、跨平台，也是全部功能的唯一落点。

本页这个 exe 只是给「不想碰命令行」的人用的图形壳：
已停止维护（deprecated）——这是最后一版，之后不再修复、不再发新版本。
想长期使用、想拿到修复和新功能，请用插件或 skill。

Read this first: the project recommends the plugin / pip line and the agent skill.
Both are maintained, supported and cross-platform, and they are where every feature
lives. The exe on this page is only a GUI shell for people who will not touch a
command line: it is deprecated — this is the final build, and it will receive no
further fixes or releases. For long-term use, install the plugin or the skill.

---

中文

三条线怎么分工

线	分工	局限
插件 / pip（首推）	全部功能所在，也是唯一持续更新的线；可嵌进 DSH 插件、可进 CI	需要 Python 3.8+（或用便携 zip 里自带的运行时）；tl gen 必须由目标游戏自带的 lib/py3-*/python.exe 跑
agent skill（首推·AI 场景）	不含代码，把同一套命令与判断教给 AI 助手	上限等于插件：本机没有工具包就跑不动；拷走目录后 scripts/rptk.py 需能找到工具包或设 RPTK_HOME
Windows exe（本页·已停止维护）	图形壳，功能与插件一致，不碰命令行	仅 Windows；界面借系统浏览器；不再修复

这个包能做什么

解压后放到游戏文件夹旁边（与游戏文件夹同级，或它的上一级），双击 renpy-toolkit.exe：
自动扫描所在目录及一级子目录里的 Ren'Py 游戏（只认真正的 Ren'Py 游戏，看 RPC2 魔数、
renpy/ 运行时、lib/py3-*、启动脚本与 game/*.rpy 证据链），弹窗让你选一个，然后点按钮。

覆盖：生成汉化骨架、校验译文、导出/回填 Excel、搬运旧译文、术语检查、硬编码扫描、
备份与回滚、字体工具、归档与反编译。

写盘边界：只有「生成汉化骨架」写进 game\tl\<语言>\；其余产物（日志、导出表格、
反编译结果、备份快照、临时文件）全部收在 exe 旁边的 renpy-toolkit-数据\。

防呆：放在磁盘根目录会弹出「危险路径，本工具停止工作」并在 10 秒后自动退出；
重复双击不会启动第二个实例；找不到游戏时直接告诉你把 exe 移到游戏旁边。

关掉网页即退出：页面每 4 秒一次心跳，20 秒没有任何请求就自己结束（判断依据是
页面在不在，不是浏览器进程在不在）。右上角「退出工具」可立即结束。

这个包的局限（请先读，再决定要不要用）

1. 已停止维护：本版之后不再有修复。要修的问题请改用插件/skill，或自行构建。
2. 仅 Windows，且体积较大（单文件约 17 MB，每次启动要解包）。
3. 界面靠系统浏览器：默认开一个无地址栏的独立窗口；个别机器上 Edge 自己的
   「无法更新 Microsoft Edge」提示页会挡住界面 —— 改用 renpy-toolkit.exe --tab
   在你现有浏览器里开标签页。
4. 受限账户可能起不来：单文件引导器需要在可写位置创建解包目录，个别机器（受限
   令牌、组策略、安全软件）会报 Could not create temporary directory。自建版本可用
   python tools/build_exe.py --runtime-tmpdir D:\rt 指定解包位置。
5. tl gen 仍需要游戏自带解释器：骨架必须由目标游戏自己的运行时给出，exe 不能代替。
6. Git 备份需要 git 2.15+；没有 git 时自动降级为 .bak。
7. 功能与插件同步，但不会再跟着插件修 bug：用得久了，两边行为会逐渐不一致。

校验

• 包内 renpy-toolkit.exe --cli --selftest 应输出 self-check passed: renpy-toolkit 1.0.0。
• 包内 使用说明.txt 写了放置位置、数据目录与三条已知限制。

许可

MIT。上游参考：renpy/renpy、
CensoredUsername/unrpyc、
Dclef/renpy-tl、
ZYKsslm/RenPy-Tutorial、
Shizmob/rpatool。

---

English

How the three lines divide the work

Line	Role	Limits
Plugin / pip (recommended)	Where every feature lives; the only line that keeps receiving updates; usable from a DSH plugin or CI	Needs Python 3.8+ (or the runtime bundled in the portable zip); tl gen must run on the target game's own lib/py3-*/python.exe
agent skill (recommended for AI use)	No code — teaches an AI assistant the same commands and judgement	Its ceiling is the plugin: it cannot run without the toolkit on the machine; if copied away, scripts/rptk.py must locate the toolkit or RPTK_HOME must be set
Windows exe (this page, DEPRECATED)	A GUI shell with the same features, no command line	Windows only; the UI borrows your system browser; no further fixes

What this package does

Unzip it beside the game folder (same level as the game folder, or its parent) and
double-click renpy-toolkit.exe. It scans its own folder and one level below, keeps only
real Ren'Py games (evidence chain: RENPY RPC2 magic, a renpy/ runtime, lib/py3-*,
a launcher that imports renpy, and game/*.rpy sources), and shows a picker.

Covered: skeleton generation, translation checks, Excel export/import, carrying old
translations over, terminology checks, hard-coded text scan, backup and rollback, font
tools, archives and decompilation.

Write boundary: only the skeleton goes into game\tl\<language>\. Everything else —
logs, exported spreadsheets, decompiled scripts, snapshots, scratch files — lands in
renpy-toolkit-数据\ beside the exe.

Guard rails: launching from a drive root shows "dangerous path, the tool stops
working" and exits after 10 seconds; a second launch does not start a second instance;
with no game found it tells you to move the exe next to the game.

Closing the page quits the tool: the page sends a heartbeat every 4 seconds; with no
request for 20 seconds the tool exits (it watches the page, not the browser process).
The "退出工具" button quits immediately.

Limits of this package (read before choosing it)

1. Deprecated — no fixes after this build. For fixes, use the plugin or the skill, or
   build your own.
2. Windows only, and large (a ~17 MB single file that unpacks on every start).
3. The UI uses your system browser: by default it opens a standalone window without
   an address bar; on some machines Edge's own "can't update Microsoft Edge" page covers
   it — use renpy-toolkit.exe --tab to open a tab in your existing browser instead.
4. Restricted accounts may fail to start: the single-file bootloader must create its
   unpack directory; some machines (restricted token, group policy, security software)
   report Could not create temporary directory. A self-built copy can pass
   --runtime-tmpdir D:\rt.
5. tl gen still needs the game's own interpreter — the skeleton must come from the
   target game's runtime; the exe cannot substitute for it.
6. Git snapshots need git 2.15+; without git the mode degrades to .bak.
7. Features match the plugin today, but bug fixes will not be backported: over time
   the two will drift apart.

Verification

• renpy-toolkit.exe --cli --selftest should print self-check passed: renpy-toolkit 1.0.0.
• 使用说明.txt inside the zip covers placement, the data folder and three known limits.

License

MIT. Upstream references: renpy/renpy,
CensoredUsername/unrpyc,
Dclef/renpy-tl,
ZYKsslm/RenPy-Tutorial,
Shizmob/rpatool.