From 1aa4a4b1a06c9b0a8334e819f570a8e8b90a5098 Mon Sep 17 00:00:00 2001
From: Akihiro Motoki <amotoki@gmail.com>
Date: Thu, 27 Jul 2017 23:20:17 +0000
Subject: [PATCH] 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               |  1 +
 doc/source/official_translator.rst |  2 +
 doc/source/tools.rst               | 80 ++++++++++++++++++++++++++++++
 doc/source/translation_stats.rst   | 11 ++--
 4 files changed, 91 insertions(+), 3 deletions(-)
 create mode 100644 doc/source/tools.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 53cff21..521e9f2 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -31,6 +31,7 @@ Contents
    translation_tips
    glossary
    translation_stats
+   tools
    i18n_team_meeting
    infra
    reviewing-translation-import
diff --git a/doc/source/official_translator.rst b/doc/source/official_translator.rst
index c44e9f5..b0c5335 100644
--- a/doc/source/official_translator.rst
+++ b/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
 --------------------------
 
diff --git a/doc/source/tools.rst b/doc/source/tools.rst
new file mode 100644
index 0000000..61f2754
--- /dev/null
+++ b/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.
diff --git a/doc/source/translation_stats.rst b/doc/source/translation_stats.rst
index 6e175d6..7e3092c 100644
--- a/doc/source/translation_stats.rst
+++ b/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.