From a Python program

To use potranslator in a python project:

from potranslator import PoTranslator

languages = ('fr', 'es', 'it')
translator = PoTranslator(pot_dir='path/to/pot_dir', locale_dir='path/to/locale_dir')

results = translator.translate_all_pot(src_lang='en', target_langs=languages, auto_save=False)

Commands, options, environment variables


Type potranslator without arguments to show the help instructions.

Basic Usage

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 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!

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 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

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

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

Setup Makefile / make.bat

make gettext will generate pot files into _build/gettext directory, however pot files can be generated in the locale/pot 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.