boardgame-rulebook-zh
将英文桌游 PDF 规则书汉化并保持原版图文位置。内置桌游术语表、表格/内嵌图标处理和自动 QA。Use when the user asks to translate or localize a board game rulebook PDF into Chinese, 汉化规则书,or when images/tables must stay aligned.
桌游规则书汉化
这个 skill 解决什么
把英文桌游 PDF 规则书翻译成中文,同时不移动、不覆盖原版的插图、棋盘、卡牌图、图标、表格线和装饰。译文按原段落的位置、字号、颜色和栏宽就地写回;表格单元、双栏、页眉页脚和内嵌图标都有专门处理。
它同时解决两个常见问题:
- 术语:内置桌游术语表,区分 worker placement / deck-building / meeple / token / exhaust 等易错词,并提供项目术语库。
- 图文错位:只擦除文字层,保留位图和矢量图;渲染后自动比对位图摘要、矢量图摘要和页面几何,任何插图移动都会报错。
适用 / 不适用
适用
- 有文字层(可选中文字)的英文 PDF 规则书,包括双栏、表格、图标、满版背景图、旋转页面。
- 用户要求“翻译成中文/汉化/保持原版排版/不要动图片”。
- 需要交付可打印 PDF,而不是重新排版的 Word/网页。
不适用
- 扫描版、纯图片 PDF、文字已转为矢量描边(无文字层)。本 skill 不会做覆盖式汉化,避免把中文盖在英文原图上。见
references/scanned-pdfs.md。 - 需要重排页面、改纸张尺寸、重画表格的“重新设计”任务。
- 连环画/漫画式对白、竖排文字、复杂表单/交互式 PDF(可尝试,但必须逐页目检)。
依赖
- Python 3.9+
- PyMuPDF(
pymupdf,测试于 1.26.5) - Pillow
- 系统中文字体(自动选择 Microsoft YaHei / PingFang / Noto Sans CJK;没有时退回 PyMuPDF 内置 CJK 字体)
python -m pip install -r requirements.txt
快速流程
# 1. 提取文字段、生成页面预览、术语命中和译文模板
python scripts/extract.py rulebook.pdf -o work
# 2. 阅读 work/source.md,填写 work/translations.tsv
# 同时检查/补充 work/termbase.tsv 与 work/glossary_hits.md
# 3. 渲染 + 自动 QA
python scripts/render.py rulebook.pdf -w work -o out
# 4. 看 out/qa/report.md 和 out/qa/pages/page_*.png
# 修译文或写 work/layout_overrides.json,重跑第 3 步
最终交付:out/rulebook_zh.pdf、out/qa/report.md、work/termbase.tsv。
QA 有 error 时不要交付。 有 warning 时逐条复核;termbase-mismatch 是 info,只作参考。
第 1 步:提取
python scripts/extract.py rulebook.pdf -o work
输出:
| 文件 | 用途 |
|---|---|
work/source.md | 按页/段列出原文、字号、对齐、bbox、表格/内嵌图标标记;带原页预览链接 |
work/segments.json | 机器可读的分段数据(渲染用) |
work/translations.tsv | 译文模板:id<TAB>中文;= 表示保留原文 |
work/termbase.tsv | 项目术语库:source<TAB>zh<TAB>category<TAB>note |
work/glossary_hits.md | 本 PDF 命中的术语表条目、建议译法、页码 |
work/original/page_*.png | 原页预览 |
work/manifest.json | 页数、字体、位图/矢量图摘要、警告 |
检查 source.md 顶部警告:
- 疑似扫描页 / 无文字层:停止覆盖式汉化,见
references/scanned-pdfs.md。 - 页面大面积被图片覆盖:确认文字是独立文字层还是烘焙在图片里。可选中文字 + 预览中文字与底图分离 = 可以继续;否则停止。
- 旋转文字:逐行旋转的文字不会自动替换;页眉页脚/页码通常不受影响。
- inline_art:该段含内嵌图标/小插图;翻译要短,并对照原页确认图标顺序。
只提取部分页做试译:--pages 1-3,5。
重新提取时默认要求 --force,并保留已有 translations.tsv / termbase.tsv;如果 id 变化,用 --reset-translations 重新生成。
第 2 步:术语库
先读 references/glossary.csv(推荐译法、avoid、wrong)和 references/glossary-notes.md(易混词解释)。
work/termbase.tsv 的规则:
- 第二列是本项目采用的译法。若官方中文版有固定译名,直接改第二列;QA 以本表为准。
- 把卡牌名、角色名、地名、组件名补进去;这些名称必须前后一致。
- 自动生成的行只是建议;
termbase-mismatch是 info,不是错误。 - wrong 列里的错译由 QA 判 error(如 meeple → 米普、deck-building → 甲板构筑)。如果某个词在本作中是特殊用法,把正确译法写进 termbase,QA 会把它视为显式覆盖。
- 官方中文版优先于本表。没有官方版时,用术语表 + 全篇一致;首次出现可加英文括号。
常用官方参考:references/official-titles.md。游戏名不要直译;没有把握就保留英文名。
第 3 步:翻译
work/translations.tsv 是唯一的译文入口:
- 第一列 id 不要改。
=:保留原文(URL、版权行、纯页码、已经中文的段落)。- 空白:缺失,QA 会报错(
--allow-missing仅用于预览)。 - 一行一段,不要写多行;换行会被合并为空格。
- 不要翻译图标、变量名、骰子记号(
2d6)、数字。
翻译时同时读 source.md 和原页预览;不要只看文字,因为图标、表格、栏宽会决定译文长度。分段翻译建议每次 20–40 段,保持术语库一致;长书可按页分批,但不要在不同批次里换译名。
文风、句式、量词、标点、卡牌名规则见 references/style.md。核心要求:
- 用“你”,不用“您”;“players”=“玩家”,“each player”=“每名玩家”。
may=可以,must=必须,cannot=不能,up to=至多,at least=至少,instead=改为。- 中文标点全角;数字与量词之间不加空格(抽2张牌)。
- 卡牌用“打出”,游戏用“进行”,抽牌用“抽”,弃牌用“弃置”,移除用“移除”,摧毁用“摧毁”。
- 不要把 “draw”(抽牌)译成“绘制”;不要把 “deck”(牌库)译成“甲板”。
- 内嵌图标段:译文尽量短,不要把图标写掉;必要时用
layout_overrides.json调整排版框。 - 译文通常比英文短;如果比原文长 1.5 倍以上,先精简。
术语/文风参考:
references/glossary.csv— 机器可读术语表references/glossary-notes.md— 易混词深解释references/style.md— 文风与句式references/official-titles.md— 常见游戏官方中文名
第 4 步:渲染 + 自动 QA
python scripts/render.py rulebook.pdf -w work -o out
输出:
out/rulebook_zh.pdfout/qa/report.md(中文)、report.jsonout/qa/pages/page_0001.png(左原文/右译文,逐页目检)out/qa/contact_sheet.png
渲染机制(简述,详见 references/layout-and-qa.md):
- 只对每行文字 bbox 加 redaction,且
fill=False、images=NONE、graphics=NONE:擦字不擦图。 - 译文优先写回原段落 bbox;空间不够时向下借用空白,但不进入其他文字、图片、表格单元。
- 表格单元译文限制在单元格内;内嵌图标用绕图排版,并从右方借用安全空白。
- 自动缩放字号(0.25pt 步进);低于 7pt 警告,低于 5.5pt 或放不下报错。
- 颜色、粗体、左/中/右对齐尽量沿用原样式。
- 字体自动选择系统 CJK;缺字会报
missing-glyphs,可用--font/--bold-font指定。
常用参数:
--font "C:/Windows/Fonts/simsun.ttc" # 衬线/羊皮纸风格规则书
--bold-font "C:/Windows/Fonts/simsun.ttc"
--allow-missing # 只做部分预览,不算最终交付
--no-previews # 不生成预览(不建议用于最终交付)
--overrides work/layout_overrides.json # 手动排版修正
第 5 步:目检 + 修正
自动 QA 通过不等于视觉通过。逐页打开 out/qa/pages/*.png,重点看:
- 插图、棋盘、卡牌图、图标是否与原文同一位置;有没有被译文盖住。
- 表格线是否完整,单元格文字有没有越界。
- 双栏有没有串栏;标题/图注是否居中。
- 内嵌图标与文字的先后顺序是否合理。
- 有没有行首标点(
。,、;:!?出现在行首)。 - 页眉页脚/页码是否在原位。
修正优先级:
- 先改译文(精简/换词),不要先缩字号。
- 仍放不下,再写
work/layout_overrides.json扩大/移动安全排版框。 - 最后才接受更小字号;低于 7pt 的正文要谨慎。
layout_overrides.json 示例(坐标是 PDF point,原点左上):
{
"p003_s008": {
"box": [28, 423, 292, 540],
"font_size": 10.0,
"align": "left",
"note": "加宽 10pt,避免逗号落到行首"
},
"p003_s034": {
"box": [297.64, 340.6, 545.0, 430.0],
"note": "略收窄,避免句号落到行首"
}
}
表格单元会被强制夹在 cell 内;overrides 不能越过表格边框。
质量门禁
out/qa/report.md 中:
- error = 0 才能交付。
- warning 逐条复核;
line-start-punctuation通常改译文或用 override 解决;small-font要确认可读性。 - info 是提示(如术语库建议、自动换字体),不是错误;但仍建议看一遍。
重点错误:
| code | 含义 | 处理 |
|---|---|---|
images-changed / vector-art-changed | 位图/矢量图位置或内容变了 | 停止交付;检查是否扫描页/特殊 PDF |
geometry-changed | 页面尺寸/旋转变了 | 停止;检查输入/输出 |
overflow / table-cell-overflow | 译文放不下/越出表格 | 精简译文或 override |
art-covered / vector-covered | 译文压住图标/插图 | 精简/override,绝不能忽略 |
text-overlap / text-overlap-source | 译文互相压/压到未翻译原文 | 精简/override |
source-residue | 原英文没擦干净 | 检查文字层/扫描页;重新渲染 |
text-not-found | 输出里找不到完整译文 | 多为缺字/字体问题;换字体或改译文 |
missing-glyphs | 字体缺字(emoji、生僻字) | 换字体或删掉非必要符号 |
missing-translation | 漏译 | 补 translations.tsv |
glossary-wrong | 命中明确错译 | 按 references/glossary.csv 改 |
line-start-punctuation | 中文标点跑到行首 | 改译文或 override |
scanned-page | 疑似扫描页 | 见 references/scanned-pdfs.md |
完整清单和逐条修法:references/qa-checklist.md。
扫描版 / 图片文字
如果 extract.py 报“没有提取到任何文字段”,或 source.md 标记扫描页:
不要直接跑渲染。扫描页上的英文是像素,擦除会破坏原图;把中文盖上去会造成图文重叠。
可选方案:
- 让用户提供有文字层的 PDF(出版社官网/官方中文版)。
- 做双语对照版:保留原页,另附按页编号的中文译文。
- 手动重排(InDesign/Affinity/Scribus)。
- OCR 生成文字层后再评估;只有确认底图干净、可安全擦字时才覆盖。
详见 references/scanned-pdfs.md。
自测
python examples/selftest.py --negative
会生成一份合成样例规则书(双栏、表格、羊皮纸/插图、内嵌位图与矢量图标),跑完整流程,并验证:
- 0 error / 0 warning;
- 页数、页面几何不变;
- 位图摘要、位置不变;
- 矢量图摘要不变;
- 表格/内嵌图标识别;
- 负向测试能拦住错译(米普)、漏译、溢出、缺字形。
最后打印 SELFTEST OK。
交付建议
对用户说明:
- 翻译了哪些页、哪些段;保留原文多少段、缺失多少段;
- QA 错误/警告数量;是否逐页目检;
- 哪些页是扫描页/未覆盖;
- 术语库和 known limitations(如内嵌图标顺序需要人工确认)。
不要把受版权保护的原始 PDF 或整页译文提交到公开仓库;本仓库的 demo 是合成样例。
文件结构
SKILL.md
scripts/
extract.py # PDF → 分段/术语命中/译文模板
render.py # 译文 → 原位 PDF + QA
pdf_common.py # 字体、几何、术语、排版工具
references/
glossary.csv # 桌游术语表(推荐/avoid/wrong)
glossary-notes.md
style.md
layout-and-qa.md
qa-checklist.md
scanned-pdfs.md
official-titles.md
examples/
make_sample.py # 合成样例规则书
selftest.py # 端到端自测
demo_page1.png # 自测生成的 demo
许可
MIT。仅用于你有权翻译的文档。
- Downloads
- 181All time
- Security audit
- Review
- Last updated
- 3w ago
- Current version
- v1.0.1
- License
- MIT-0
