RenderDoc 官方文档中文翻译

RenderDoc v1.47 官方文档（https://renderdoc.org/docs/）的完整本地镜像与中文翻译， 专业术语采用「中文（English）」双语形式，每页右下角可一键切换中英原文。

目录结构

en/      原站完整镜像（115 个 HTML + _static/_images 资源）
zh/      翻译后的站点（本地浏览入口 zh/index.html）
tools/   提取 / 合并 / 渲染管线脚本
trans/   翻译工作文件
  zh_000.tsv … zh_013.tsv   翻译批次（id \t 译文）
  zh_merged.json            合并后的 模板→译文 表（渲染时读取）
units.json / units.jsonl    提取出的 3275 个翻译单元（jsonl = 一行一单元，行号 = id+1）

本地浏览

cd zh
python -m http.server 8934
# 浏览器打开 http://127.0.0.1:8934/index.html

（不要直接双击 HTML——Sphinx 站点的相对资源在 file:// 下部分浏览器会拦截。）

翻译范围

• 90 个手写文档页（index / introduction / getting_started / behind_scenes / how / window / in_application_api / python_api 两个手写入口页等）：正文全部翻译。
• genindex / search / python_api/renderdoc|qrenderdoc 下的 API 参考页： 自动生成页保留英文，页首插入中文说明横幅（.rdz-note）。
• 保留英文不译：人名列表（贡献者名单）、品牌名（RenderDoc / Sphinx / Read the Docs）、 代码块 / 键盘快捷键 / 菜单路径中的程序字符串。
• 覆盖率：3220 / 3275 单元已翻译，其余均为上述有意保留项。

翻译约定

• 术语首次出现用「中文（English）」双语，如 捕获（Capture）、绘制调用（Drawcall）、 管线状态（Pipeline State）、像素历史（Pixel History）、推送常量（Push Constant）； 之后同类术语单用中文。
• 标题、侧栏导航、正文目录树（toctree）、面包屑、上一页/下一页、图片 alt 均翻译； <title> 后缀译为「RenderDoc 文档」。
• 行内代码 / API 名（如 debugmarker、CTRL-0、Print Screen）保持原样。

再渲染流程

修改 trans/zh_*.tsv 或管线脚本后：

cd 本目录

# 1) 重新提取（仅当 en/ 镜像内容变化时需要）
python tools/extract.py

# 2) 合并 TSV 并校验（重复 id / 未知 id / 占位符 {N} 多重集不一致都会报错退出）
python tools/merge.py > trans/zh_merged.json

# 3) 逐页渲染（stdin 进、stdout 出，避免脚本内部写路径）
find en -name "*.html" | sed 's|^en/||' | sort > pages.txt
fails=0; while read -r rel; do
  python tools/render_page.py "$rel" < "en/$rel" > "zh/$rel" || { fails=$((fails+1)); echo "FAIL $rel"; }
done < pages.txt; echo "fails=$fails"

管线原理

1. extract.py：把每个块级元素（p/h1-h6/li/dt/dd/caption 等）的行内内容渲染为 模板字符串，行内元素（a/strong/em/span…）变为 {N} 占位符，code/pre/kbd/img 为 不透明占位符；占位符子树的文字递归提取为子单元；侧栏导航链接、图片 alt （alt:: 前缀）单独提取。按模板去重 → units.json。
2. merge.py：id \t 译文 格式的 TSV 合并为 JSON 表，并做占位符多重集校验 （模板与译文中的 {N} 集合必须一致），防止翻译时吞/错占位符。
3. render_page.py：按与提取完全相同的遍历逻辑定位元素，命中模板则将原文 存入 data-en 属性并替换为译文；对占位符子树（段内链接、目录树链接等） 递归应用子单元译文；注入浮动 EN/中文 切换按钮（交换 data-en/data-zh 的 innerHTML）。

已知限制

• search.html 的全文搜索仍索引英文原文（Sphinx 静态搜索 JS）。
• API 参考页（autodoc 生成）未翻译，仅加横幅说明。
• 中英切换按元素粒度交换 innerHTML，切换后整页一致，但不记忆状态、不写 URL 参数。

来源与许可

• 原文镜像自 https://renderdoc.org/docs/ （RenderDoc v1.47）， 文档源文件来自 baldurk/renderdoc 仓库的 docs/ 目录。
• RenderDoc 以 MIT License 发布，版权归 Baldur Karlsson 所有；本仓库为其中文翻译再分发， 附原许可声明如下：

Copyright (c) 2015-2024, Baldur Karlsson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.