============
potranslator
============


.. image:: https://img.shields.io/pypi/v/potranslator.svg
        :target: https://pypi.python.org/pypi/potranslator
        :alt: Pypi Python Package Index Status

.. image:: https://img.shields.io/travis/SekouD/potranslator.svg
        :target: https://travis-ci.org/SekouD/potranslator
        :alt: Linux Continuous Integration Status

.. image:: https://ci.appveyor.com/api/projects/status/liecctj9hj0qwc7q/branch/master?svg=true
        :target: https://ci.appveyor.com/project/SekouD/potranslator
        :alt: Windows Continuous Integration Status

.. image:: https://readthedocs.org/projects/potranslator/badge/?version=latest
        :target: https://potranslator.readthedocs.io/en/latest/?badge=latest
        :alt: Documentation Status

.. image:: https://pyup.io/repos/github/SekouD/potranslator/shield.svg
        :target: https://pyup.io/repos/github/SekouD/potranslator/
        :alt: Depedencies Update Status

.. image:: https://codecov.io/gh/SekouD/potranslator/branch/master/graph/badge.svg
        :target: https://codecov.io/gh/SekouD/potranslator.
        :alt: Code Coverage Status

.. image:: https://snyk.io/test/github/SekouD/potranslator/badge.svg?targetFile=requirements.txt
        :target: https://snyk.io/test/github/SekouD/potranslator?targetFile=requirements.txt
        :alt: 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:

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

      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 and Build the compiled mo files:

    .. code-block:: console

        $ potranslator build
        $ make -e SPHINXOPTS="-D language='ja'" 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:

.. code-block:: console

    $ pip install potranslator

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

.. code-block:: console

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

.. code-block:: console

   $ export 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:: console

   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

.. _Sphinx: http://sphinx-doc.org
.. _sphinx-intl: https://pypi.org/project/sphinx-intl
.. _transifex: https://transifex.com
.. _transifex-client: https://pypi.python.org/pypi/transifex-client
.. _setuptools: https://pypi.python.org/pypi/setuptools
.. _six: https://pypi.python.org/pypi/six
.. _babel: https://pypi.python.org/pypi/babel
.. _click: https://pypi.python.org/pypi/click
.. _googletrans: https://pypi.org/project/googletrans
.. _polib: https://pypi.org/project/polib
