Локализация¶

Добавлено в версии 1.1.

Complementary to translations provided for Sphinx-generated messages such as navigation bars, Sphinx provides mechanisms facilitating the translation of documents. See the Options for internationalisation for details on configuration.

../../_images/translation.svg — Workflow visualization of translations in Sphinx. (The figure is created by plantuml.)¶

Детали локализации Sphinx ¶

gettext [1] является установленным стандартом для интернационализации и локализации. Он просто сопоставляет сообщения в программе с переведенной строкой. Sphinx использует эти средства для полного перевода документов.

Initially project maintainers have to collect all translatable strings (also referred to as messages) to make them known to translators. Sphinx extracts these through invocation of sphinx-build -M gettext.

Каждый элемент в структуре документа (doctree) будет помещен в отдельное сообщение, в результате получается список фрагментов, которые будут равнозначны фрагментам исходного документа хотя большие абзацы будут оставаться столь же крупными. Это дает бесшовные обновления документа обеспечивая контекст для переводчиков в свободной части текста. Задача сопровождающего-разбить абзацы, которые слишком велики, так как нет вменяемого автоматизированного способа сделать это.

После успешного вызова класса MessageCatalogBuilder вы сможете найти набор файлов .pot в выходном каталоге. Они являются перечнем шаблонов и содержат сообщения только на языке оригинала.

Они могут быть предоставлены переводчикам, которые преобразуют их в файлы .po — которые называются каталогами сообщений — содержащими соответствие между оригинальными сообщениями и сообщениями на целевом языке.

gettext compiles them into a binary format known as binary catalogs through msgfmt for efficiency reasons. If you make these files discoverable with locale_dirs for your language, Sphinx will pick them up automatically.

An example: you have a document usage.rst in your Sphinx project. The gettext builder will put its messages into usage.pot. Imagine you have Spanish translations [2] stored in usage.po — for your builds to be translated you need to follow these instructions:

Compile your message catalog to a locale directory, say locale, so it ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory (where es is the language code for Spanish.)
```
msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
```
Установите параметр locale_dirs в ["locale/"].
Установите параметр language в es (так же возможно через командную строку -D).
Выполните необходимую сборку.

In order to protect against mistakes, a warning is emitted if cross-references in the translated paragraph do not match those from the original. This can be turned off globally using the suppress_warnings configuration variable. Alternatively, to turn it off for one message only, end the message with #noqa like this:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa

(Write \#noqa in case you want to have «#noqa» literally in the text. This does not apply to code blocks, where #noqa is ignored because code blocks do not contain references anyway.)

Добавлено в версии 4.5: The #noqa mechanism.

Перевод через sphinx-intl ¶

Краткое руководство ¶

sphinx-intl is a useful tool to work with Sphinx translation flow. This section describe an easy way to translate with sphinx-intl.

Install sphinx-intl.
```
$ pip install sphinx-intl
```
Add configurations to conf.py.
```
locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.
```
This case-study assumes that BUILDDIR is set to _build, locale_dirs is set to locale/ and gettext_compact is set to False (the Sphinx document is already configured as such).
Extract translatable messages into pot files.
```
$ make gettext
```
The generated pot files will be placed in the _build/gettext directory. If you want to customize the output beyond what can be done via the Options for internationalisation, the default pot file template can be replaced by a custom message.pot.jinja file placed in any directory listed in templates_path.
Generate po files.

We’ll use the pot files generated in the above step.
```
$ sphinx-intl update -p _build/gettext -l de -l ja
```
Once completed, the generated po files will be placed in the below directories:
- ./locale/de/LC_MESSAGES/
- ./locale/ja/LC_MESSAGES/

Translate po files.

As noted above, these are located in the ./locale/<lang>/LC_MESSAGES directory. An example of one such file, from Sphinx, builders.po, is given below.

# a5600c3d2e3d48fc8c261ea0284db79b
#: ../../builders.rst:4
msgid "Available builders"
msgstr "<FILL HERE BY TARGET LANGUAGE>"

В другом случае, если msgid содержит многострочный текст содержащий синтаксические конструкции reStructuredText:

# 302558364e1d41c69b3277277e34b184
#: ../../builders.rst:9
msgid ""
"These are the built-in Sphinx builders. More builders can be added by "
":ref:`extensions <extensions>`."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."

Please be careful not to break reStructuredText notation. Most po-editors will help you with that.

Build translated document.

You need a language parameter in conf.py or you may also specify the parameter on the command line.

For BSD/GNU make, run:
```
$ make -e SPHINXOPTS="-D language='de'" html
```
For Windows cmd.exe, run:
```
> set SPHINXOPTS=-D language=de
> .\make.bat html
```
For PowerShell, run:
```
PS> Set-Item env:SPHINXOPTS "-D language=de"
PS> .\make.bat html
```

Поздравляем! Теперь ваша переведенная документация находится в каталоге _build/html.

Добавлено в версии 1.3: sphinx-build that is invoked by make command will build po files into mo files.

If you are using 1.2.x or earlier, please invoke sphinx-intl build command before make command.

Перевод ¶

Обновите ваши po-файлы из новых файлов pot ¶

If a document is updated, it is necessary to generate updated pot files and to apply differences to translated po files. In order to apply the updates from a pot file to the po file, use the sphinx-intl update command.

$ sphinx-intl update -p _build/gettext

Использование сервиса Transifex для работы в команде ¶

Transifex is one of several services that allow collaborative translation via a web interface. It has a nifty Go-based command line client that makes it easy to fetch and push translations.

Install the Transifex CLI tool.

You need the tx command line tool for uploading resources (pot files). The official installation process place the tx binary file in the current directory along with a README and a LICENSE file, and adds the current directory to $PATH.
```
$ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
```
См. также

Документация Transifex Client
Create your Transifex account and create a new project and an organization for your document.

Currently, Transifex does not allow for a translation project to have more than one version of the document, so you’d better include a version number in your project name.

Например:

Organization ID:

sphinx-document

ID проекта:

sphinx-document-test_1_0

URL проекта:

https://www.transifex.com/projects/p/sphinx-document-test_1_0/
Create an API token to be used in the command-line.

Go to your Transifex API token page and generate a token. Copy the generated token now, as you will not be able to see it again later.

Set your Transifex API token in the user configuration file $HOME/.transifexrc.

[https://app.transifex.com]
rest_hostname = https://rest.api.transifex.com
token         = paste_your_api_token_here

Alternatively, you can store your Transifex API token as the environment variable TX_TOKEN, which is recognized and used by tx.
```
$ export TX_TOKEN=paste_your_api_token_here
```
Create the project’s config file for tx command.

This process will create .tx/config in the current directory.
```
$ cd /your/document/root
$ tx init

Successful creation of '.tx/config' file
```

Upload pot files to Transifex service.

Register pot files to .tx/config file using sphinx-intl update-txconfig-resources, adjusting --pot-dir value to your project’s pot files“ directory:

$ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
  --transifex-organization-name=sphinx-document \
  --transifex-project-name=sphinx-document-test_1_0

You can use the SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME and SPHINXINTL_TRANSIFEX_PROJECT_NAME environment variables instead of the respective command line arguments.

См. также

sphinx-intl update-txconfig-resources documentation

и загрузите файлы pot:

$ tx push -s
# Getting info about resources

sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done

# Pushing source files

sphinx-document-test_1_0.builders - Uploading file
sphinx-document-test_1_0.builders - Done

Forward the translation on Transifex.

Pull translated po files and make translated HTML.

Get translated catalogs and build mo files. For example, to build mo files for German (de):

$ cd /your/document/root
$ tx pull -l de
# Getting info about resources

sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done

# Pulling files

sphinx-document-test_1_0.builders [de] - Pulling file
sphinx-document-test_1_0.builders [de] - Creating download job
sphinx-document-test_1_0.builders [de] - Done

Invoke make html (for BSD/GNU make) passing the language code:

$ make -e SPHINXOPTS="-D language='de'" html

И всё!

Совет

Локальный перевод и перевод на Transifex

If you want to push all language’s po files, you can be done by using tx push -t command. Watch out! This operation overwrites translations in Transifex.

Другими словами, если вы обновили каждый из файлов на сервисе и локальные po-файлы, может потребоваться много времени и сил чтобы объединить их.

Using Weblate service for team translation ¶

Участие в переводе справочной информации Sphinx ¶

Рекомендованным способом для новых переводчиков справочной информации Sphinx, является участие в команде переводчиков на Transifex.

There is a sphinx translation page for Sphinx (master) documentation.

Login to Transifex service.
Перейдите на страницу переводов sphinx.
Кликните Запрос языка и заполните форму.
Wait acceptance by Transifex sphinx translation maintainers.
(After acceptance) Translate on Transifex.

Detail is here: https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator

Translation progress and statistics ¶

Добавлено в версии 7.1.0.

During the rendering process, Sphinx marks each translatable node with a translated attribute, indicating if a translation was found for the text in that node.

The translation_progress_classes configuration value can be used to add a class to each element, depending on the value of the translated attribute.

The |translation progress| substitution can be used to display the percentage of nodes that have been translated on a per-document basis.

Сноски