Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

A python package to easily translate po and pot files in any language supported by Google Translate.

Project description

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


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
potranslator-1.0.4-py2.py3-none-any.whl (16.1 kB) Copy SHA256 hash SHA256 Wheel py2.py3
potranslator-1.0.4.tar.gz (28.8 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page