Pypi Python Package Index Status Linux Continuous Integration Status Windows Continuous Integration Status Documentation Status Depedencies Update Status Python 3 Readiness Code Coverage Status Code Vulnerability Status

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:

  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

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


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


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:


On the Windows command line:


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.


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


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