potranslator 1.0.4

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


=======
History
=======

1.0.0 (2018-07-05)
------------------

* First release candidate.
* Added Command Line Interface.


0.1.0 (2018-06-27)
------------------

* First release on PyPI.