企业官网建设流程全解析

Diffusers 文档多语言翻译完整指南：从 Issue 认领到 doc-builder 本地预览

【免费下载链接】diffusers🤗 Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers

导读

本文以 docs/TRANSLATING.md 为骨架，系统讲解如何为 Diffusers 文档库贡献全新的语言翻译。作为"让机器学习民主化"愿景的一部分，Diffusers 仓库将所有官方文档按语言组织在 docs/source 目录下，目前已包含英文、简体中文（zh）、日语（ja）、韩语（ko）、葡萄牙语（pt）等多个语言版本。读完本文，你将掌握完整的翻译协作工作流：认领章节、Fork 仓库、按语言代码复制英文文档、翻译站点目录与正文，并借助仓库内置的校验脚本与 doc-builder 完成质量保证和本地预览。

背景：为什么 Diffusers 需要社区翻译

Diffusers 是目前生态最完整的扩散模型库之一，覆盖图像、视频与音频生成。它的官方文档（位于 docs/source/en，仓库中约含 377 篇 Markdown 文档与配套的_toctree.yml目录文件）随代码库同步演进。为了让全球不同语言的开发者都能无障碍上手，仓库维护者欢迎社区贡献者把整套文档翻译到更多语言——这正是 docs/TRANSLATING.md 这份指南存在的意义。

仓库对多语言文档的组织方式非常直观：docs/source是唯一的一级文档目录，内部按语言代码分子目录，每种语言拥有独立的正文文件与自己的_toctree.yml。例如：

每种语言子目录的结构都与英文版平行，这保证了站点构建工具只需按语言代码切换目录即可产出完整站点。

第一步：在 Issues 中登记语言与章节

翻译是多人协作任务，开工前必须先确认"有没有人已经做过、正在做"，避免重复劳动。推荐的流程是：

1. 前往仓库的 Issues 页面，检索是否存在针对你目标语言的翻译登记 issue；
2. 若不存在，从 "New issue" 按钮下选择"🌐 Translating a New Language?"模板新建 issue；
3. issue 建立后，在该 issue 下评论说明你想负责的章节，维护者会把你的名字登记到认领列表里。

这一流程的关键作用是"避免撞车"——文档体量大、章节多，明确的认领机制能让多位贡献者并行推进各自章节，最后由维护者统一合入。

第二步：Fork 并克隆仓库

翻译最终以 Pull Request 的形式合入，因此你首先需要一份自己的仓库副本：

1. 在代码托管平台点击仓库页面右上角的Fork按钮，得到你的用户名/diffusers；
2. 将你的 fork 克隆到本地（以镜像源为例，也可替换为你 fork 后的地址）：

git clone https://gitcode.com/GitHub_Trending/di/diffusers.git cd diffusers

克隆完成后，建议为后续同步上游改动预留 remote，并基于新分支开始翻译，便于最终以干净的历史提交 PR。

第三步：复制英文文档并建立你的语言目录

目录结构说明

全部文档材料都收纳在docs/source这一个主目录下，按语言分子目录。你需要翻译的源文件全部位于docs/source/en，不要动其他语言目录。

一条命令建立语言骨架

进入你本地仓库的docs目录，把整个英文目录复制成目标语言目录：

cd docs cp -r source/en source/<LANG-ID>

这里的<LANG-ID>必须是ISO 639-1（两字母）或 ISO 639-2（三字母）语言代码。仓库内实际使用的代码就是现成范例：zh（中文）、ja（日文）、ko（韩文）、pt（葡萄牙文）。不要使用中文拼音或其他自定义缩写，因为站点构建、链接路由都依赖标准的语言代码。

复制完成之后，你就得到了一个完整的待翻译骨架，接下来只需把.md正文与_toctree.yml中的文字逐步替换为目标语言，文件路径与文件数量保持不变。

第四步：先翻译站点目录_toctree.yml

翻译正文之前，TRANSLATING 指南强烈建议先处理_toctree.yml——它是渲染网站侧边栏导航（Table of Contents）的关键文件。

_toctree.yml的字段语义

_toctree.yml由树状结构组成，每个叶子节点对应一个文档章节，包含两个核心字段：

TRANSLATING.md 中给出的参考片段如下：

- sections: - local: pipeline_tutorial # Do not change this! Use the same name for your .md file title: Pipelines for inference # Translate this! ... title: Tutorials # Translate this!

注意注释中的强约束：local字段只是.md文件名的映射（如pipeline_tutorial对应pipeline_tutorial.md），它同时被链接系统复用，一旦改名会导致文件 404；真正需要翻译的是title字段。

仓库实际目录文件与"老格式"的差异

仓库中不同语言、不同历史时期的_toctree.yml在顶层写法上有细微差异，但local+title的配对语义完全一致。例如英文版 docs/source/en/_toctree.yml 顶层元素形如：

- sections: - local: index title: Diffusers - local: installation title: Installation - local: quicktour title: Quickstart - local: stable_diffusion title: Basic performance title: Get started - isExpanded: false sections: - local: using-diffusers/loading title: DiffusionPipeline ... title: Pipelines

而中文版 docs/source/zh/_toctree.yml 则演示了"标题被本地化"后的样子：

- title: 开始Diffusers sections: - local: index title: Diffusers - local: installation title: 安装 - local: quicktour title: 快速入门 - local: stable_diffusion title: 有效和高效的扩散

对照两份文件可以看到翻译时的处理原则：

• local原样保留（如index、installation、quicktour），因为对应的installation.md、quicktour.md文件名在两种语言中都存在；
• title自由翻译（如Installation → 安装、Quickstart → 快速入门）；
• 顶层章节分组名（Get started、Tutorials等）同样属于待翻译对象。

目标语言还没有_toctree.yml怎么办

如果你负责的语言是全新的，docs/source/<LANG-ID>/目录下可能尚未存在_toctree.yml。此时直接从英文版复制一份，然后删除与你当前翻译章节无关的部分即可——只要你确认最终文件存在于docs/source/<LANG-ID>/_toctree.yml这个固定位置。在复制第 3 步中整个英文目录时该文件会一并被带过来，通常无需额外手工创建。

第五步：翻译章节正文 Markdown 文件

目录文件就绪后，就进入正式翻译环节——把该章节对应的.md文档内容译成目标语言。

• 文档正文与_toctree.yml的对应关系是"文件名一致"：_toctree.yml中local: quicktour，对应正文文件就是quicktour.md；
• TRANSLATING.md 将正文文件称为 MDX（Markdown + 自定义组件），Diffusers 文档中大量使用了[[autodoc]]这类 doc-builder 指令，用来把 Python 类与方法源码中的 docstring 自动注入文档页；
• 翻译时保留所有代码块、命令、内链语法与[[autodoc]]指令的原有形式，只翻译叙述性文字。例如在中文文档里，docs/source/zh/quicktour.md 与英文quicktour.md共享相同的 API 调用示例，区别仅在解说文字；
• 所有.md文件开头都带有 Apache License 2.0 版权头（<!--Copyright ... -->注释块），翻译版应予以保留，这与英文原版保持一致的许可声明。

正文文件较多时，可以像日文版 docs/source/ja（目前仅有installation、quicktour、stable_diffusion等入门章节）那样分阶段推进，先翻译《Get Started》章节让页面立即可用，再逐步补齐后续章节。仓库里 docs/source/ko/in_translation.md 这类文件说明：可以按需用独立页面标注"部分章节仍在翻译中"的状态，方便读者与审阅者了解进度。

第六步：本地构建与预览（质量保障）

翻译完成后，如何在提交前检查页面效果？仓库的 docs/README.md 给出了标准流程。

先安装构建文档所需的依赖（在仓库根目录执行，[docs]为可选的文档构建扩展依赖）：

pip install -e ".[docs]"

同时需要安装 Hugging Face 开源的doc-builder文档构建工具（具体安装命令见 docs/README.md）。之后可用 doc-builder 在本地起一个实时预览服务：

doc-builder preview {package_name} {path_to_docs}

例如预览英文文档：

doc-builder preview diffusers docs/source/en

预览你自己的翻译时，把路径换成你的语言目录即可：

doc-builder preview diffusers docs/source/zh

浏览器访问http://localhost:3000即可查看渲染结果。doc-builder 会监听文件变化自动刷新，方便边译边查。有两个使用要点（同样来自 docs/README.md）：

• preview命令只能识别已存在的文档文件；当你新增了一个全新的.md文件时，必须先把它的文件名（不带扩展名）登记进_toctree.yml，然后按ctrl-c停止预览并重新执行preview命令；
• 本地构建仅用于检查排版效果，构建产物无需提交到仓库。

仓库内置的目录质量校验

除了 doc-builder 渲染，仓库还提供了用于维护英文目录结构的工具脚本 utils/check_doc_toc.py。它以docs/source/en/_toctree.yml为检查对象，自动完成两件事：

• 查重：统计同一local值在目录中出现的次数，若同一文档被多次引用，或同一个local配了不同title，脚本会直接抛错，提示只保留一份并统一标题；
• 排序/去重：除少数固定置顶项（如overview、autopipeline）外，按title对 API 文档条目做字母序整理，保证导航结构稳定、可预期。

从脚本实现（如PATH_TO_TOC = "docs/source/en/_toctree.yml"、FIXED_POSITION_TITLES = {"overview", "autopipeline"}）可以看出它主要服务于英文主目录，但其维护思路对所有语言通用：翻译版本应保持"每个local唯一、标题一致、结构清晰"的纪律，这样既可避免站内链接冲突，也让后续的自动化检查与多语言对照更顺畅。

协作收尾：让更多人加入你的章节

翻译往往是大工程。如果你希望社区伙伴共同翻译自己负责的章节，可以在原 issue 下继续沟通协作分工；仓库维护者会在此过程中协助协调、合并与发布（例如在 docs/TRANSLATING.md 中建议的维护者认领方式）。翻译经 review 合入后，新的语言版本即可与英文文档一同出现在官方文档站点中，被全球用户检索与使用。

小结：一份翻译提交的最终检查清单

对照 docs/TRANSLATING.md 与仓库现状，一次规范的多语言翻译贡献应满足：

1. 已登记：目标语言与认领章节已在 Issues 中确认，无重复劳动；
2. 目录就绪：docs/source/<LANG-ID>/已从docs/source/en复制而来，目录内包含_toctree.yml；
3. 导航已翻译：_toctree.yml的local字段与文件名一一对应、原样保留，title与分组标题完成本地化，且不存在重复local；
4. 正文已翻译：各章节.md叙述文字完成翻译，代码、命令、[[autodoc]]指令与文件头的 Apache 版权声明保持原样；
5. 预览验证：通过doc-builder preview diffusers docs/source/<LANG-ID>在本地确认页面渲染正常、侧边栏跳转有效；
6. 提交合入：基于 fork 的分支提交翻译，发起 Pull Request 等待维护者 review。

沿着上述流程，你就能把 Diffusers 庞大而活跃的官方文档带入你的语言社区——让更多开发者绕开语言障碍，直接上手图像、视频与音频的扩散模型生成。

延伸阅读：文档写作规范（docstring 风格、[[autodoc]]用法、图片托管约定）见 docs/README.md；英文主目录结构见 docs/source/en/_toctree.yml，中文翻译范例见 docs/source/zh。

【免费下载链接】diffusers🤗 Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers