NEKOPARTY STUDIO

编译多语言离线版本Godot官方文档教程

Godot 文档 Sphinx
字数统计: 1.8k阅读时长: 8 min
2025/08/06
loading

前言

希望这篇文档能给建设Godot国内社区贡献一点微薄的力量。

拉取文档

首先从Github上拉取Godot文档源码。首先，我们去拉取翻译文件的Repo。

1
git clone https://github.com/godotengine/godot-docs-l10n.git

这个翻译文件的Repo官方文档上没有提及，也很难找，总之就是纯恶心人的。

Branch列表

可以看到这个里面包含了很多Branch。考虑到翻译文本只是一个单纯定义了一个对原始文本的替换文件，因此只是按大版本划分了一下，不需要按Latest，Stable之类的进行区别。

下面进入这个文件夹

1
cd godot-docs-l10n

在这个文件夹下拉取Godot文档本体的Repo。

1
git clone https://github.com/godotengine/godot-docs.git

Branch列表

注意，实际上Stable和Latest版本的区分在这些Branch里。除此之外，把这个Branch列表往下拉就能看见3.x的版本。按需取用对应的版本即可。

修改源码

原本的语言和版本选择器完全依赖于Read the docs在线托管工具实现的，为了离线编译也能有用需要简单修改一下源码。

找到godot-docs/_templates/versions.html，替换成以下内容。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{# Add rst-badge after rst-versions for small badge style. #}
{% set display_version = version -%}
{% set listed_languages = ({"en":"en", "zh_CN":"zh_CN"}).items() -%}
{% set listed_versions = ({"stable":"stable", "latest":"latest"}).items() -%}

{% if READTHEDOCS and current_version %}
  {% set display_version = current_version -%}
{% endif %}
{% if READTHEDOCS and versions %}
  {% set listed_versions = versions -%}
{% endif %}

<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
  <span class="rst-current-version" data-toggle="rst-current-version">
    <span class="fa fa-book"> Read the Docs</span>
    v: {{ display_version }}{% if display_version != godot_version %} ({{ godot_version }}){% endif %}
    <span class="fa fa-caret-down"></span>
  </span>
  <div class="rst-other-versions">
    {#
      The contents of this element will be replaced in production.
      But we can still have some mock data for testing.
    #}

    <dl>
      <dt>{{ _('Languages') }}</dt>
      {% for slug, url in listed_languages %}
        {% set target_url = "/" + version + "/" + slug + "/" + pagename + ".html" %}
        <dd><a href="{{ target_url }}">{{ slug }}</a></dd>
      {% endfor %}
    </dl>
    <dl>
      <dt>{{ _('Versions') }}</dt>
      {% for slug, url in listed_versions %}
        {% set target_url = "/" + slug + "/" + current_language + "/" + pagename + ".html" %}
        <dd><a href="{{ target_url }}">{{ slug }}</a></dd>
      {% endfor %}
    </dl>
    <dl>
      {# Translators: The phrase "Read the Docs" is not translated #}
      <dt>{{ _('On Read the Docs') }}</dt>
        <dd>
          <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}">{{ _('Project Home') }}</a>
        </dd>
        <dd>
          <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/builds/">{{ _('Builds') }}</a>
        </dd>
        <dd>
          <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/downloads/">{{ _('Downloads') }}</a>
        </dd>
    </dl>

    <hr>
    <small>
      <span>Hosted by <a href="https://readthedocs.org">Read the Docs</a></span>
      <span> · </span>
      <a href="https://docs.readthedocs.io/page/privacy-policy.html">Privacy Policy</a>
    </small>

    {##}
  </div>
</div>

该文件主要修改了版本与语言切换按钮的路径处理方式。原本的路径处理方式完全不可用，会直接被Read the docs的API替换。不用管后面我改了什么，只需要看第三第四行。

1
2
{% set listed_languages = ({"en":"en", "zh_CN":"zh_CN"}).items() -%}
{% set listed_versions = ({"stable":"stable", "latest":"latest"}).items() -%}

如需添加语言，只需要在listed_languages里添加对应语言标识即可。listed_versions同理，编译时保证文件夹名和这个一致就行。

为了正常工作，还需要简单修改一下godot-docs/conf.py。在html_context的最后加上一行即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
html_context = {
    "display_github": not is_i18n,  # Integrate GitHub
    "github_user": "godotengine",  # Username
    "github_repo": "godot-docs",  # Repo name
    "github_version": "master",  # Version
    "conf_py_path": "/",  # Path in the checkout to the docs root
    "godot_docs_title": supported_languages[language],
    "godot_docs_basepath": "https://docs.godotengine.org/",
    "godot_docs_suffix": ".html",
    # Distinguish local development website from production website.
    # This prevents people from looking for changes on the production website after making local changes :)
    "godot_title_prefix": "" if on_rtd else "(DEV) ",
    # Set this to `True` when in the `latest` branch to clearly indicate to the reader
    # that they are not reading the `stable` documentation.
    "godot_is_latest": True,
    "godot_version": "4.5",
    # Enables a banner that displays the up-to-date status of each article.
    "godot_show_article_status": True,
    # Display user-contributed notes at the bottom of pages that don't have `:allow_comments: False` at the top.
    "godot_show_article_comments": on_rtd and not is_i18n,
    "current_language": language,
}

即加上最后一行current_language。如果想把浏览器标题上的(DEV)去掉，把godot_title_prefix这一项改了就行。

以上内容按理来说都能写个脚本在拉取最新版代码之后自动完成，但我懒得写了。

配置编译环境

推荐使用Python的VirtualEnv来完成环境配置。

1
2
3
4
5
6
7
8
9
# 创建虚拟环境
python3 -m venv godot-docs-venv
# 激活这个环境（以后每次编译之前都得保证已经激活）
source godot-docs-venv/bin/activate
# 安装依赖
pip3 install --upgrade pip setuptools
# 进入docs的Repo文件夹，安装依赖
cd /path/to/godot-docs
pip3 install -r requirements.txt

这样就完成了环境配置。编译之前只需要激活环境即可。

编译

因为对版本和语言选择器源码进行了一些修改，所以编译时得保证路径一致。这里提供一个我使用的Latest版本编译脚本，将这个脚本放在godot-docs的Latest版本Branch目录下，执行即可编译。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#!/bin/bash
# 清理旧编译文件夹
rm -rf _build

# 定义编译路径
# 为了方便nginx用，直接编译到反向代理的文件夹下面得了
# 如有需要，自己修改这两个变量就行
base_dir="/var/www/docs/"
version="latest"

# 构建英语版本
export READTHEDOCS_LANGUAGE=en
unset SPHINX_TAGS
sphinx-build -b html . ${base_dir}${version}/en -j6

# 构建简体中文版本
export READTHEDOCS_LANGUAGE=zh_CN
export SPHINX_TAGS=i18n
sphinx-build -b html . ${base_dir}${version}/zh_CN -j6

注意，由于文档比较巨大，每个编译进程需要8G以上的内存。麻烦自行选择进程数量。

这样就完事了，之后用Nginx去反向代理编译出来的根目录就行，然后配置一个到默认页面的重定向。

1
2
3
4
5
6
7
8
9
10
11
12
server {
    listen 80;
    server_name 不告诉你;
    
    root /var/www/docs;
    
    # 处理根路径重定向到英文首页
    location = / {
        # 301永久重定向到英文首页
        return 301 /stable/en/index.html;
    }
}

如果你想预览效果的话，可以访问挂在本站下的离线文档查看。由于文档过大我只编译了Latest版本的，所以那个切换版本的按钮是不起作用的😫。

CATALOG
  1. 1. 前言
  2. 2. 拉取文档
  3. 3. 修改源码
  4. 4. 配置编译环境
  5. 5. 编译
Total : 6
2025
Godot Shader 计算机图形 角色Worflow序列 文档 Sphinx 杂记 Blender MMD 模型