Как интернационализировать Sphinx (i18n)

Из значений по умолчанию, следующих за выполнением sphinx-quickstart, как мне получить каталоги для конкретного языка, например те, которые используются Read The Docs?

Я запускаю новый сайт документации Sphinx, размещенный на GitHub Pages, созданный с помощью GitHub Actions и использующий тему Read The Docs. По сути, я пытаюсь воссоздать Read The Docs, но без рекламы или поиска на стороне сервера.

Я еще долго не смогу ничего переводить, но я хочу убедиться, что мой новый проект будет готов к переводу позже. В частности, я хочу убедиться, что постоянные ссылки на мою документацию не изменятся после добавления переводов. С этой целью я хотел бы, чтобы URL-адрес моей документации включал язык в URL-адресе (/en/stable/), например:

Я следовал Руководству Sphinx по интернационализации и установил language и locale_dirs переменные в conf.py:

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 со значениями по умолчанию для сборки html для конкретного языка с помощью make?


internationalization locale python-sphinx read-the-docs
person Michael Altfield    schedule 13.07.2020    source источник

Ответы (1)


arrow_upward
3
arrow_downward

Недокументированная правда заключается в том, что sphinx этого не делает. Фактически, функциональность sphinx i18n останавливается, если не считать рабочего процесса для создания всех каталогов, специфичных для вашего языка. Подразумевается, что вы должны спроектировать и обернуть sphinx-build своими собственными сценариями, чтобы настроить это.

Чтобы перевести ваши reST-файлы sphinx на другой язык, вам не нужно обновлять сами файлы '.rst'. Sphinx уже понимает, как выглядит блок текста, и может разделить строки заголовков, подписи, абзацы, разделенные двойным символом новой строки, и т. д. на уникальные исходные строки (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', показывающий две строки на главной странице нашей документации, которые мы переведем с английского на испанский.

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 подготовить несколько файлов '.po' для испанского языка назначения из наших файлов исходного языка '.pot', сгенерированных выше.

Прежде чем приступить к этому шагу, вам необходимо установить 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). Идеальный.

Если мы выполним поиск нового испанского файла '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) на испанском языке.

Для получения дополнительной информации см. эту статью о как настроить интернационализация в Sphinx.

person Michael Altfield    schedule 23.07.2020
comment
Вы также можете изучить возможность использования rinoh для создания PDF-файлов с помощью sphinx ="nofollow noreferrer">github.com/maltfield/rtd-github-pages/blob/ - person Michael Altfield; 20.08.2020