=====
Usage
=====

From a Python program
=====================

To use potranslator in a python project:

.. code-block:: python

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

Commands
--------

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:

    .. code-block:: console

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

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

    .. code-block:: python

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

    .. code-block:: console

        $ make gettext


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

    .. code-block:: console

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

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

   .. code-block:: console

        ./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):

    .. code-block:: console

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


    Command line (for Windows cmd.exe):

    .. code-block:: console

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

    Command line (for PowerShell):

    .. code-block:: console

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

.. code-block:: console

   $ export POTRANSLATOR_LANGUAGE=de,ja

On the Windows command line:

.. code-block:: console

    > set POTRANSLATOR_LANGUAGE=de,ja

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

.. code-block:: console

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


Setup sphinx conf.py
--------------------

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

.. code-block:: python

   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.

.. _Sphinx: http://sphinx-doc.org
