下面是调整后的默认语言为简体中文，并添加英文翻译的具体操作步骤：

---

一、Sphinx本地配置调整

1. 修改conf.py
   将默认语言设置为中文，并声明支持英文：

   language = 'zh_CN'  # 默认语言改为中文
   locale_dirs = ['locale/']  # 翻译文件目录不变
   gettext_compact = False
   

2. 生成翻译模板
   生成包含所有可翻译字符串的.pot模板文件：

   sphinx-build -b gettext ./source build/gettext
   

3. 创建英文翻译文件
   生成英文的.po文件（注意 -l en）：

   sphinx-intl update -p build/gettext -l en
   

   生成的英文翻译文件路径：
   locale/en/LC_MESSAGES/

4. 翻译英文内容
   使用工具（如Poedit）编辑 locale/en/LC_MESSAGES/*.po 文件，填充英文翻译。

5. 构建多语言文档
   分别构建中英文版本：

   # 构建中文版（默认）
   sphinx-build -b html -D language=zh_CN ./source build/html/zh_CN# 构建英文版
   sphinx-build -b html -D language=en ./source build/html/en
   

---

二、Read the Docs云端调整

1. 项目关联关系

   • 主项目：docs-zh_CN（中文文档仓库）
   • 翻译项目：docs-en（英文文档仓库）

2. 后台设置

   • 在中文主项目的 Translations 设置中，添加英文翻译项目并关联语言代码 en
   • 确保英文子项目启用自动构建

---

三、前端语言切换调整

在模板文件（如 layout.html）中修改链接：

<div class="language-switcher"><a href="/zh_CN/">中文</a> | <a href="/en/">English</a>
</div>

---

四、关键注意事项

1. 语言代码规范

   • 中文使用 zh_CN（简体中文）
   • 英文使用 en（通用英语）

2. 文件结构验证
   确保翻译文件路径符合以下结构：

   locale/
   ├── en/
   │   └── LC_MESSAGES/
   │       ├── index.po
   │       └── other.po
   └── zh_CN/└── LC_MESSAGES/├── index.po└── other.po
   

3. Read the Docs URL规则

   • 中文版：https://项目名.readthedocs.io/zh_CN/
   • 英文版：https://项目名.readthedocs.io/en/

---

五、维护更新流程

1. 更新翻译模板
   当文档内容修改后：

   # 重新生成模板
   sphinx-build -b gettext ./source build/gettext# 合并到英文翻译文件
   sphinx-intl update -p build/gettext -l en
   

2. 验证翻译文件
   检查英文翻译文件格式：

   msgfmt -c -o /dev/null locale/en/LC_MESSAGES/index.po
   

---

效果示例

• 默认访问中文文档：https://project.readthedocs.io/zh_CN/
• 通过页面右下角或自定义切换按钮跳转英文版

如果使用Read the Docs官方主题，系统会自动生成语言切换菜单（无需手动添加HTML代码）。

---

翻译英语内容工作流程

一、准备工作

1. 安装 Poedit
   Poedit 是一个常用的 .po 文件编辑工具，支持跨平台。可以从 Poedit 官网下载并安装。

2. 安装翻译工具
   选择一个支持批量翻译的工具，例如：

   • 在线翻译工具（如 智能翻译官）。
   • Python 翻译库（如 googletrans 或 translate）。

3. 准备 .po 文件
   如果你已经有 .po 文件，可以直接使用。如果没有，可以通过以下方式生成：

   • 使用 xgettext 工具从代码中提取字符串生成 .pot 文件，然后将其复制为 .po 文件。
   • 使用 Poedit 的“新建翻译”功能，指定源文件或目录生成 .po 文件。

---

二、提取中文内容

1. 打开 .po 文件
   使用 Poedit 打开你的 .po 文件。你会看到左侧是原始文本（通常是英文），右侧是翻译文本（中文）。

2. 导出中文内容
   如果需要批量翻译，可以手动提取所有中文内容，或者使用脚本提取。例如，使用 Python 脚本读取 .po 文件并提取 msgstr 中的中文内容。

   import redef extract_translations(po_file_path):translations = []with open(po_file_path, 'r', encoding='utf-8') as file:content = file.readlines()for line in content:match = re.match(r'^msgstr\s+"(.*)"$', line)if match:translations.append(match.group(1))return translationstranslations = extract_translations('your_file.po')
   print(translations)
   

---

三、自动翻译为英文

1. 使用在线翻译工具
   将提取的中文内容逐条翻译为英文。例如，使用 智能翻译官 或其他在线翻译工具，将中文内容粘贴进去，获取英文翻译。

2. 使用 Python 自动翻译
   如果需要批量处理，可以使用 Python 脚本调用翻译 API（如 Google Translate API）进行自动翻译。以下是一个示例代码：

   from googletrans import Translatortranslator = Translator()def translate_to_english(text):return translator.translate(text, src='zh-cn', dest='en').texttranslations = extract_translations('your_file.po')
   english_translations = [translate_to_english(t) for t in translations]
   print(english_translations)
   

---

四、填充英文翻译到 .po 文件

1. 手动填充
   打开 Poedit，将翻译后的英文内容逐条填入 msgstr 中。

2. 使用脚本填充
   如果翻译内容较多，可以使用脚本将翻译后的英文内容写入 .po 文件。以下是一个简单的示例：

   def fill_translations(po_file_path, translations):with open(po_file_path, 'r', encoding='utf-8') as file:content = file.readlines()new_content = []translation_index = 0for line in content:if line.startswith('msgstr "'):new_content.append(f'msgstr "{translations[translation_index]}"\n')translation_index += 1else:new_content.append(line)with open(po_file_path, 'w', encoding='utf-8') as file:file.writelines(new_content)fill_translations('your_file.po', english_translations)
   

---

五、保存和编译

1. 保存 .po 文件
   在 Poedit 中保存修改后的 .po 文件。

2. 编译为 .mo 文件
   Poedit 会自动编译 .po 文件为 .mo 文件，或者可以手动运行以下命令：

   msgfmt -o output.mo input.po
   

---

注意事项

1. 翻译质量：自动翻译工具的翻译质量可能有限，建议人工校对。
2. 版权问题：使用在线翻译工具时，需注意版权和隐私问题。
3. Poedit 配置：确保 Poedit 的源路径和关键字配置正确，以便正确提取和更新翻译内容。

参考链接：

1. https://zhuanlan.zhihu.com/p/427843476