potranslator

potranslator is a package to easily translate po and pot files generated by Sphinx or other tools in any language supported by Google Translate.

potranslator auto-detects the language in the original pot files and auto-translates the pot files into the supplied target languages.

The Command Line Interface of potranslator and its documentation are based on sphinx-intl.

Optional: supports the Transifex collaborative service to upload the auto-generated translations to transifex for collaborative corrections of the translations.

Supported Languages

• Afrikaans af
• Albanian sq
• Amharic am
• Arabic ar
• Armenian hy
• Azeerbaijani az
• Basque eu
• Belarusian be
• Bengali bn
• Bosnian bs
• Bulgarian bg
• Catalan ca
• Cebuano ceb (ISO-639-2)
• Chinese (Simplified) zh-CN (BCP-47)
• Chinese (Traditional) zh-TW (BCP-47)
• Corsican co
• Croatian hr
• Czech cs
• Danish da
• Dutch nl
• English en
• Esperanto eo
• Estonian et
• Finnish fi
• French fr
• Frisian fy
• Galician gl
• Georgian ka
• German de
• Greek el
• Gujarati gu
• Haitian Creole ht
• Hausa ha
• Hawaiian haw (ISO-639-2)
• Hebrew iw
• Hindi hi
• Hmong hmn (ISO-639-2)
• Hungarian hu
• Icelandic is
• Igbo ig
• Indonesian id
• Irish ga
• Italian it
• Japanese ja
• Javanese jw
• Kannada kn
• Kazakh kk
• Khmer km
• Korean ko
• Kurdish ku
• Kyrgyz ky
• Lao lo
• Latin la
• Latvian lv
• Lithuanian lt
• Luxembourgish lb
• Macedonian mk
• Malagasy mg
• Malay ms
• Malayalam ml
• Maltese mt
• Maori mi
• Marathi mr
• Mongolian mn
• Myanmar (Burmese) my
• Nepali ne
• Norwegian no
• Nyanja (Chichewa) ny
• Pashto ps
• Persian fa
• Polish pl
• Portuguese (Portugal, Brazil) pt
• Punjabi pa
• Romanian ro
• Russian ru
• Samoan sm
• Scots Gaelic gd
• Serbian sr
• Sesotho st
• Shona sn
• Sindhi sd
• Sinhala (Sinhalese) si
• Slovak sk
• Slovenian sl
• Somali so
• Spanish es
• Sundanese su
• Swahili sw
• Swedish sv
• Tagalog (Filipino) tl
• Tajik tg
• Tamil ta
• Telugu te
• Thai th
• Turkish tr
• Ukrainian uk
• Urdu ur
• Uzbek uz
• Vietnamese vi
• Welsh cy
• Xhosa xh
• Yiddish yi
• Yoruba yo
• Zulu zu

Quick Start for auto-translation with potranslator

This section describes how to translate documents generated by Sphinx with the potranslator command.

1. Create your document(s) by using Sphinx:

   $ sphinx-build -b html /path/to/docs path/to/docs/_build

2. Optionally add the settings to your conf.py if you have one:

   locale_dirs = ['locale/']   #path is an example but this is the recommended path.
   gettext_compact = False     #optional.

   locale_dirs is required and gettext_compact is optional.

3. Extract the document's translatable messages into pot files (make sure you are in the folder containing make.bat and Makefile if you are on windows):

   $ make gettext

4. Translate/Update your documents in German and Japanese:

   $ potranslator update -p _build/gettext -l de -l ja

   Done. You got these directories that contain po files with auto-translated entries:

   ./locale/de/LC_MESSAGES/
   ./locale/ja/LC_MESSAGES/

5. Translate/Update your documents in Japanese, build the compiled mo files and generate the translated html documents:

   Command line (for Unix systems):

   $ potranslator build
   $ make -e SPHINXOPTS="-D language='ja'" html

   Command line (for Windows cmd.exe):

   > set SPHINXOPTS=-D language=de
   > potranslator build
   > .\make.bat html

   Command line (for PowerShell):

   > Set-Item env:SPHINXOPTS "-D language=de"
   > potranslator build
   > .\make.bat html

That's all!

Basic Features

• Translate from pot files or update existing po files with auto-generated translation.
• Build mo files from translated po or pot files.

Requirements for the basic features

• Python 3.6, 3.5, 3.4, 2.7, pypy.
• external libraries: setuptools, six, babel, click, googletrans, polib

Optional features

These features need the transifex-client library.

• create a .transifexrc file from an environment variable, without interactive input.
• create a .tx/config file without interactive input.
• update a .tx/config file from locale/pot files automatically.
• build mo files from po files in the locale directory.

You need to use the tx command to use the following features:

• tx push -s : push pot (translation catalogs) to transifex.
• tx pull -l ja : pull po (translated catalogs) from transifex.

Requirements for the optional features

• Your transifex account if you want to upload/download po files from transifex.
• external library: transifex-client

Installation

It is strongly recommended to use virtualenv for this procedure:

$ pip install potranslator

If you want to use the Optional Features, you need install this additional library:

$ pip install potranslator[transifex]

Commands, options, environment variables

Commands

Type potranslator without arguments to show the help instructions.

Setup environment variables

All command-line options can be set with environment variables using the format POTRANSLATOR_<UPPER_LONG_NAME> .

Dashes (-) have to replaced with underscores (_).

For example, to set the target languages:

$ export POTRANSLATOR_LANGUAGE=de,ja

On the Windows command line:

> set POTRANSLATOR_LANGUAGE=de,ja

This is the same as passing the option to potranslator directly:

$ potranslator <command> --language=de --language=ja

Setup sphinx conf.py

Add the following settings to your sphinx document's conf.py if it exists:

locale_dirs = ['locale/']   #for example
gettext_compact = False     #optional

Setup Makefile / make.bat

make gettext will generate pot files into the _build/gettext directory, however pot files can be generated in the locale/pot directory if convenient.

You can do that by replacing _build/gettext with locale/pot in your Makefile and/or make.bat that was generated by sphinx-quickstart.

License

Licensed under the BSD license. See the LICENSE file for specific terms.

Original

The Command Line Interface and the transifex integration of potranslator are adapted from sphinx-intl.

• https://pypi.org/project/sphinx-intl

CHANGES

See: https://github.com/SekouD/potranslator/blob/master/HISTORY.rst