Internationalization 如何国际化斯芬克斯（i18n）

从执行

sphinx quickstart

后的默认设置中，如何获取特定于语言的目录，如读取文档所使用的目录

我正在启动一个新的Sphinx文档站点，该站点由GitHub页面托管，使用GitHub操作构建，并使用“阅读文档”主题。基本上，我试图重新创建阅读文档，但没有广告或服务器端搜索

在很长一段时间内，我将无法实际翻译任何东西，但我确实希望确保我的新项目可以在以后进行翻译。最具体地说，我希望确保在添加翻译后，文档的永久链接不会更改。为此，我想让我的文档URL包含URL中的语言（

/en/stable/

），例如：

我遵循并在

conf.py

中设置

语言

和

locale\u dirs

变量：

language = 'en'
locale_dirs = ['locale/']
gettext_compact = True

不幸的是，在进行上述更改之后，

make html

和

make-e SPHINXOPTS=“-D language='en'”html

仍然会生成没有

en

子目录的文件

user@host:~/docs$ tree -L 2 _build
_build
├── doctrees
│   ├── environment.pickle
│   └── index.doctree
└── html
    ├── genindex.html
    ├── index.html
    ├── objects.inv
    ├── search.html
    ├── searchindex.js
    ├── _sources
    └── _static

---

我遗漏了什么还是文档遗漏了什么？如何设置一个全新的Sphinx安装，默认情况下使用

make

生成特定于语言的html？

未记录的事实是Sphinx不这样做。事实上，sphinx i18n功能在构建所有特定于语言的目录时缺少工作流。这意味着您必须使用自己的脚本来设计和包装

sphinx build

，以进行设置

要将sphinx reST文件转换为另一种语言，不必更新“.rst”文件本身。Sphinx已经了解文本块的外观，它可以将标题字符串、标题、双换行符分隔的段落等分割为唯一的“源字符串”（msgid），并将它们放入“.pot”源语言文件和“.po”目标语言文件中

首先，从“docs/”目录运行

makegettext

。这将告诉sphinx解析reST文件，并自动找到一组要翻译的字符串，并给它们一个唯一的

msgid

user@host:~/rtd-github-pages$ cd docs/
user@host:~/rtd-github-pages/docs$ ls
autodoc.rst  buildDocs.sh  conf.py.orig  locales   Makefile
_build       conf.py       index.rst     make.bat  _static
user@host:~/rtd-github-pages/docs$ 
 
user@host:~/rtd-github-pages/docs$ make gettext
Running Sphinx v1.8.4
making output directory...
building [gettext]: targets for 0 template files
building [gettext]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
writing message catalogs... [100%] index                                        
build succeeded.
 
The message catalogs are in _build/gettext.
user@host:~/rtd-github-pages/docs$ 

上述执行应创建以下文件

user@host:~/rtd-github-pages/docs$ ls _build/gettext/
autodoc.pot  index.pot
user@host:~/rtd-github-pages/docs$ 

这里有一个来自“_build/gettext/index.pot”的片段，在我们文档的主页上显示了两个字符串，我们将把它们从英语翻译成西班牙语

user@host:~/rtd-github-pages/docs$ grep -m2 -A2 .rst _build/gettext/index.pot 
#: ../../index.rst:7
msgid "Welcome to helloWorld's documentation!"
msgstr ""
--
#: ../../index.rst:9
msgid "Contents:"
msgstr ""
user@host:~/rtd-github-pages/docs$ 

接下来，让我们告诉sphinx从上面生成的源lananguage.pot文件准备一些西班牙语目标语言.po文件

在继续执行此步骤之前，您需要安装

sphinx intl

和python

Stemmer

模块。如果您使用的是基于Debian的发行版，那么可以使用以下命令

sudo apt-get install -y sphinx-intl python3-stemmer

执行以下命令以准备特定于西班牙语的翻译文件

user@host:~/rtd-github-pages/docs$ sphinx-intl update -p _build/gettext -l es
Create: locales/es/LC_MESSAGES/index.po
Create: locales/es/LC_MESSAGES/autodoc.po
user@host:~/rtd-github-pages/docs$ 

上述执行创建了两个“.po”文件：每个“.pot”源语言文件一个，直接与两个“.rst”文件（index.rst和autodoc.rst）相关。太好了

如果我们grep新的特定于西班牙语的“docs/locales/es/LC_MESSAGES/index.po”文件，我们会看到它与源“.pot”文件的内容相同

user@host:~/rtd-github-pages/docs$ grep -m2 -A2 .rst locales/es/LC_MESSAGES/index.po 
#: ../../index.rst:7
msgid "Welcome to helloWorld's documentation!"
msgstr ""
--
#: ../../index.rst:9
msgid "Contents:"
msgstr ""
user@host:~/rtd-github-pages/docs$ 

这些特定于语言的“.po”文件是我们实际进行翻译的地方。如果您是一个大型项目，那么您可能需要使用一个特殊的程序或翻译这些文件。但是，为了清楚起见，我们将直接编辑这些文件

user@host:~/rtd-github-pages/docs$ perl -pi -0e "s^(msgid \"Welcome to helloWorld's documentation\!\"\n)msgstr \"\"^\1msgstr \"¡Bienvenido a la documentación de helloWorld\!\"^" locales/es/LC_MESSAGES/index.po
user@host:~/rtd-github-pages/docs$ perl -pi -0e "s^(msgid \"Contents:\"\n)msgstr \"\"^\1msgstr \"Contenidos:\"^" locales/es/LC_MESSAGES/index.po
user@host:~/rtd-github-pages/docs$ 
 
user@host:~/rtd-github-pages/docs$ grep -m2 -A2 .rst locales/es/LC_MESSAGES/index.po 
#: ../../index.rst:7
msgid "Welcome to helloWorld's documentation!"
msgstr "¡Bienvenido a la documentación de helloWorld!"
--
#: ../../index.rst:9
msgid "Contents:"
msgstr "Contenidos"
user@host:~/rtd-github-pages/docs$ 

如您所见，上面的执行将

msgstr”“

的内容填充为其上方对应的

msgid

行的原始（英语）西班牙语翻译

现在，让我们构建两个版本的html静态内容：[1]英语版本和[2]西班牙语版本

user@host:~/rtd-github-pages/docs$ sphinx-build -b html . _build/html/en -D language='en'
Running Sphinx v1.8.4
loading translations [en]... done
making output directory...
building [mo]: targets for 0 po files that are out of date
building : targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
generating indices... genindex py-modindex
highlighting module code... [100%] helloWorld                                   
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
 
The HTML pages are in _build/html/en.
user@host:~/rtd-github-pages/docs$
 
user@host:~/rtd-github-pages/docs$ sphinx-build -b html . _build/html/es -D language='es'
Running Sphinx v1.8.4
loading translations [es]... done
making output directory...
building [mo]: targets for 1 po files that are out of date
writing output... [100%] locales/es/LC_MESSAGES/index.mo                        
building : targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
generating indices... genindex py-modindex
highlighting module code... [100%] helloWorld                                   
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in Spanish (code: es) ... done
dumping object inventory... done
build succeeded.
 
The HTML pages are in _build/html/es.
user@host:~/rtd-github-pages/docs$
 
user@host:~/rtd-github-pages/docs$ firefox _build/html/en/index.html _build/html/es/index.html &
[1] 12134
user@host:~/rtd-github-pages/docs$ 

上述执行中的

firefox

命令应通过两个选项卡打开浏览器：（1）英语和（2）西班牙语

user@host:~/rtd-github-pages/docs$ sphinx-build -b html . _build/html/en -D language='en'
Running Sphinx v1.8.4
loading translations [en]... done
making output directory...
building [mo]: targets for 0 po files that are out of date
building : targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
generating indices... genindex py-modindex
highlighting module code... [100%] helloWorld                                   
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
 
The HTML pages are in _build/html/en.
user@host:~/rtd-github-pages/docs$
 
user@host:~/rtd-github-pages/docs$ sphinx-build -b html . _build/html/es -D language='es'
Running Sphinx v1.8.4
loading translations [es]... done
making output directory...
building [mo]: targets for 1 po files that are out of date
writing output... [100%] locales/es/LC_MESSAGES/index.mo                        
building : targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
generating indices... genindex py-modindex
highlighting module code... [100%] helloWorld                                   
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in Spanish (code: es) ... done
dumping object inventory... done
build succeeded.
 
The HTML pages are in _build/html/es.
user@host:~/rtd-github-pages/docs$
 
user@host:~/rtd-github-pages/docs$ firefox _build/html/en/index.html _build/html/es/index.html &
[1] 12134
user@host:~/rtd-github-pages/docs$ 

---

有关更多信息，请参阅上的这篇文章。

未记录的事实是斯芬克斯没有这样做。事实上，sphinx i18n功能在构建所有特定于语言的目录时缺少工作流。这意味着您必须使用自己的脚本来设计和包装

sphinx build

，以进行设置

要将sphinx reST文件转换为另一种语言，不必更新“.rst”文件本身。Sphinx已经了解文本块的外观，它可以将标题字符串、标题、双换行符分隔的段落等分割为唯一的“源字符串”（msgid），并将它们放入“.pot”源语言文件和“.po”目标语言文件中

首先，从“docs/”目录运行

makegettext

。这将告诉sphinx解析reST文件，并自动找到一组要翻译的字符串，并给它们一个唯一的

msgid

user@host:~/rtd-github-pages$ cd docs/
user@host:~/rtd-github-pages/docs$ ls
autodoc.rst  buildDocs.sh  conf.py.orig  locales   Makefile
_build       conf.py       index.rst     make.bat  _static
user@host:~/rtd-github-pages/docs$ 
 
user@host:~/rtd-github-pages/docs$ make gettext
Running Sphinx v1.8.4
making output directory...
building [gettext]: targets for 0 template files
building [gettext]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
writing message catalogs... [100%] index                                        
build succeeded.
 
The message catalogs are in _build/gettext.
user@host:~/rtd-github-pages/docs$ 

上述执行应创建以下文件

user@host:~/rtd-github-pages/docs$ ls _build/gettext/
autodoc.pot  index.pot
user@host:~/rtd-github-pages/docs$ 

这里有一个来自“_build/gettext/index.pot”的片段，在我们文档的主页上显示了两个字符串，我们将把它们从英语翻译成西班牙语

user@host:~/rtd-github-pages/docs$ grep -m2 -A2 .rst _build/gettext/index.pot 
#: ../../index.rst:7
msgid "Welcome to helloWorld's documentation!"
msgstr ""
--
#: ../../index.rst:9
msgid "Contents:"
msgstr ""
user@host:~/rtd-github-pages/docs$ 

接下来，让我们告诉sphinx从上面生成的源lananguage.pot文件准备一些西班牙语目标语言.po文件

在继续执行此步骤之前，您需要安装

sphinx intl

和python

Stemmer

模块。如果您使用的是基于Debian的发行版，那么可以使用以下命令

sudo apt-get install -y sphinx-intl python3-stemmer

执行以下命令以准备特定于西班牙语的翻译文件

user@host:~/rtd-github-pages/docs$ sphinx-intl update -p _build/gettext -l es
Create: locales/es/LC_MESSAGES/index.po
Create: locales/es/LC_MESSAGES/autodoc.po
user@host:~/rtd-github-pages/docs$ 

上述执行创建了两个“.po”文件：每个“.pot”源语言文件一个，直接与两个“.rst”文件（index.rst和autodoc.rst）相关。太好了

如果我们grep新的特定于西班牙语的“docs/locales/es/LC_MESSAGES/index.po”文件，我们会看到它与源“.pot”文件的内容相同

user@host:~/rtd-github-pages/docs$ grep -m2 -A2 .rst locales/es/LC_MESSAGES/index.po 
#: ../../index.rst:7
msgid "Welcome to helloWorld's documentation!"
msgstr ""
--
#: ../../index.rst:9
msgid "Contents:"
msgstr ""
user@host:~/rtd-github-pages/docs$ 

这些特定于语言的“.po”文件是我们实际进行翻译的地方。如果你是一个大项目