Translating Documentation
=========================

If you wish to help translate the Salt documentation to your language, please 
head over to the `Transifex`_ website and `signup`__ for an account.

Once registered, head over to the `Salt Translation Project`__, and either 
click on **Request Language** if you can't find yours, or, select the language 
for which you wish to contribute and click **Join Team**.

`Transifex`_ provides some useful reading resources on their `support 
domain`__, namely, some useful articles `directed to translators`__.


.. __: https://www.transifex.com/signup/
.. __: https://www.transifex.com/projects/p/salt/
.. __: http://support.transifex.com/
.. __: http://support.transifex.com/customer/portal/topics/414107-translators/articles


Building A Localized Version of the Documentation
-------------------------------------------------

While you're working on your translation on `Transifex`_, you might want to 
have a look at how it's rendering.


Install The Transifex Client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To interact with the `Transifex`_ web service you will need to install the 
`transifex-client`__:

.. code-block:: bash

    pip install transifex-client


.. __: https://github.com/transifex/transifex-client



Configure The Transifex Client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once installed, you will need to set it up on your computer. We created a 
script to help you with that:

.. code-block:: bash

    .scripts/setup-transifex-config



Download Remote Translations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There's a little script which simplifies the download process of the 
translations(which isn't that complicated in the first place).
So, let's assume you're translating ``pt_PT``, Portuguese(Portugal). To 
download the translations, execute from the ``doc/`` directory of your Salt 
checkout:

.. code-block:: bash


    make download-translations SPHINXLANG=pt_PT


To download ``pt_PT``, Portuguese(Portugal) and ``nl``, Dutch, you can use the 
helper script directly:

.. code-block:: bash

    .scripts/download-translation-catalog pt_PT nl


Build Localized Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After the download process finishes, which might take a while, the next step is 
to build a localized version of the documentation.
Following the ``pt_PT`` example above:

.. code-block:: bash

    make html SPHINXLANG=pt_PT


View Localized Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open your browser, point it to the local documentation path and check the 
localized output you've just build.


.. _`Transifex`: https://www.transifex.com