Недокументированная правда в том, что сфинкс этого не делает. Фактически, функциональность sphinx i18n не ограничивается рабочим процессом для создания всех ваших языковых каталогов c. Подразумевается, что вы должны разработать и обернуть sphinx-build своими собственными сценариями, чтобы настроить это.
Чтобы перевести файлы sphinx reST на другой язык, вам не нужно обновлять файлы '.rst' самих себя. Sphinx уже понимает, как выглядит блок текста, и может разделять строки заголовков, подписи, абзацы, разделенные двумя символами новой строки, и т. Д. c на уникальные «исходные строки» (msgid) и помещать их в '.pot файлы исходного языка и файлы целевого языка .po.
Сначала запустите make gettext из каталога 'docs /'. Это говорит 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', показывающий две строки на главной странице нашей документации, которые мы переведем с английского sh на испанский sh.
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 подготовить несколько файлов испанского sh целевого языка '.po' из сгенерированных выше файлов исходного языка '.pot'.
Перед тем, как продолжить этот шаг, вы: Вам потребуется установить sphinx-intl и модуль python Stemmer. Если вы используете дистрибутив на основе Debian, вы можете сделать это с помощью следующей команды.
sudo apt-get install -y sphinx-intl python3-stemmer
Выполните следующую команду, чтобы подготовить наши файлы перевода sh -specifi c на испанский язык.
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 и autodo c .rst). Идеально.
Если мы встретим новый файл Spani sh -specifi c 'docs / locales / es / LC_MESSAGES / index.po', мы увидим, что он имеет то же содержимое, что и исходный файл '.pot 'file.
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$
Эти c файлы' .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 "" с испанским sh переводом соответствующего Строка msgid над ним на исходном (Engli sh) языке.
Теперь давайте создадим две версии нашего html stati c содержимого: [1] на английском sh и [2 ] на испанском sh.
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) на английском sh и (2) на испанском sh .
Для получения дополнительной информации см. Эту статью о как настроить интернационализацию в Sphinx .