Add documentation on i18n tools

In the parent commit we suggest to sync the translator list with
Zanata rather than adding individual translator one by one.
It is better the document covers this, but there is no good place
to explain these tooling so far.
This commit adds a page on tools.

Change-Id: I238e5bdcfe89ed86d0e5e0ded13d6abe2f2fb484

doc/source/index.rst

@@ -31,6 +31,7 @@ Contents
    translation_tips
    glossary
    translation_stats
+   tools
    i18n_team_meeting
    infra
    reviewing-translation-import

doc/source/official_translator.rst

@@ -62,6 +62,8 @@ finish following steps:
    by contributing translations.
    You can find :doc:`various ways of contributions <contributing>`.
 
+.. _i18n-atc:
+
 ATC status in I18n project
 --------------------------
 

doc/source/tools.rst

@@ -0,0 +1,80 @@
+=====
+Tools
+=====
+
+This page covers various operations around i18n activities.
+
+Project maintenance
+-------------------
+
+.. note::
+
+   The scripts below depend on several python modules.
+   To install these dependencies, run ``pip install -e requirements.txt``.
+
+   More convenient way is to use **tox** like
+   ``tox -e venv -- python <script-name>``.
+
+   **tox** is available on PyPI and also available in various Linux
+   distribution. ``pip install tox`` or ``apt-get install python-tox``
+   (in case of Ubuntu) installs **tox**.
+
+.. _sync-translator-list:
+
+Sync the translator list with Zanata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The I18n project maintains a list of language teams and their members.
+The list is used by Stackalytics to gather translation statistics
+(See :ref:`stats-stackalytics` for detail). It is also used by the
+scripts below.
+
+The filename of the list is ``tools/translation_team.yaml``.
+
+This list is a cache of information on Zanata, and we need to keep it
+synced with Zanata.
+
+To sync the translator list, run the following command:
+
+.. code-block:: console
+
+   tox -e zanata-users-sync
+
+The above run the following internally:
+
+.. code-block:: console
+
+   python tools/zanata/zanata_users.py --output-file tools/zanata/translation_team.yaml
+
+Retrieve translation statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`ATC status in I18n project <i18n-atc>` is determined based on
+translation statistics in a specific period.
+
+The script ``tools/zanata/zanata_stats.py`` helps retrieving
+translation statistics from Zanata.
+
+To run the script:
+
+.. code-block:: console
+
+   tox -e venv -- python ./tools/zanata/zanata_stats.py <options>
+
+``--help`` option shows the detail usage.
+
+Extract Zanata user information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At the moment, the I18n PTL needs to maintain the ATC list of the I18n
+project manually around the end of each release cycle.
+This requires name and e-mail address of individual translators.
+
+The script ``tools/zanata/zanata_userinfo.py`` helps this.
+It generates a CSV file by reading a YAML file which contains the list
+of translators (e.g., ``translation_team.yaml``) with user name and
+e-mail addresses by interacting with Zanata API.
+
+.. note::
+
+   This script requires Zanata admin privilege.

doc/source/translation_stats.rst

@@ -4,6 +4,8 @@ Translation Statistics
 
 There are several ways to know your translation activity.
 
+.. _stats-zanata:
+
 Zanata
 ------
 
@@ -17,6 +19,8 @@ Zanata provides ways to know your activity on Zanata.
 
 Note that you need to log into Zanata to see your activity in the above pages.
 
+.. _stats-stackalytics:
+
 Stackalytics
 ------------
 
@@ -40,9 +44,10 @@ Here is the check list for such case:
 * Is your Zanata ID different from your launchpad ID?
 
 If your Zanata ID is not included in the translator list,
-you need to add your Zanata ID to the list.
-Contact your language coordinator, email the i18n mailing list,
-or submit a patch to add your ID by yourself.
+you need to update the list to include your Zanata ID.
+Contact your language coordinator, email the i18n mailing list.
+You can also submit a patch to update the list by yourself
+(For detail, see :ref:`sync-translator-list`).
 
 .. TODO (amotoki):
    We need a guide for language coordinators.