Sphinx-intl is a utility tool with several features that make it easy to translate and apply translation, using PO files, to Sphinx-generated documentation. It also includes functionality to support a workflow to push and pull files using the Transifex Client.
Sphinx docs can also be localized using Transifex Live, our JavaScript-based technology. Transifex Live is well suited for web pages and lets translators work in context, increasing the overall translation quality.
Below, you'll find instructions for localizing your documentation using either Sphinx-intl with PO files or Transifex Live.
Localize Sphinx using PO files
Before getting started, you'll want to follow the Sphinx instructions and internationalize your website. Once you have done this, there will be at least one source file under a path that looks like locale/en/LC_MESSAGES/, assuming English is your source language.
The source file will be the foundation for setting up the Transifex Client, which lets you send and receive files over Transifex's REST API. To set up your Transifex Client configuration, you first need a project in Transifex, and the Transifex Client installed.
After finishing all the steps above, follow the set of commands below to set up your repository configuration in a file called .tx/config. In this example, we named our project in Transifex mytxproject.
$ cd /your/document/root $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \ --transifex-project-name mytxproject
You should commit the .tx/config file to your repository, so the next time you want to push new source content, you can use the following commands:
$ cd /your/document/root $ sphinx-intl update -p _build/locale $ tx push -s
Once you have a translation complete for your files, let's say for German (de), you can pull the translated files using the command below:
$ cd /your/document/root $ tx pull -t -l de
To build the localized version of your docs in German, you can run:
$ cd /your/document/root $ sphinx-intl build $ make -e SPHINXOPTS="-D language='de'" html
💡Tip: You can also use Transifex Live to translate your Sphinx-generated docs. To learn more, check out the Transifex Live documentation.
💡Tip
Looking for more help? Get support from our Transifex Community Forum!
Find answers or post to get help from Transifex Support and our Community.