working transifex workflow

Closes #666

5 files changed, 69 insertions, 35 deletions

diff --git a/docs/dev/internationalization.rst b/docs/dev/internationalization.rst
index 6cbc6f72..e6b89dea 100644
--- a/docs/dev/internationalization.rst
+++ b/docs/dev/internationalization.rst
@@ -6,24 +6,22 @@ Internationalization
 This part of the documentation covers the localization and translation of LEAP Client.
 Because we want to *bring fire to the people*, in as many countries and languages as possible.
 
-.. note::
-   We should probably move the translators info to a top level section of the docs, and leave this
-   as internal/tech-savvy notes.
-
 Translating the LEAP Client PyQt Application
 --------------------------------------------
 
 .. raw:: html
 
-   <div> <a target="_blank" style="text-decoration:none; color:black; font-size:66%" href="https://www.transifex.com/projects/p/leap-client/resource/leap_client_es/" title="See more information on Transifex.com">Top translations: leap-client » leap_client_es</a><br/> <img border="0" src="https://www.transifex.com/projects/p/leap-client/resource/leap_client_es/chart/image_png"/><br/><a target="_blank" href="https://www.transifex.com/"><img border="0" src="https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png"/></a></div>
+   <div><a target="_blank" style="text-decoration:none; color:black; font-size:66%" href="https://www.transifex.com/projects/p/leap-client/resource/leap-client/" title="See more information on Transifex.com">Top translations: leap-client » leap-client</a><br/><img border="0" src="https://www.transifex.com/projects/p/leap-client/resource/leap-client/chart/image_png"/><br/><a target="_blank" href="https://www.transifex.com/"><img border="0" src="https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png"/></a></div>
 
 
 For translators
 ^^^^^^^^^^^^^^^
 .. note::
-   ... unfinished
+   We should probably move the translators info to a top level section of the docs, and leave this
+   as internal notes.
 
-We are using `transifex <http://transifex.com/projects/p/leap-client>`_ site to coordinate translation efforts. If you want to contribute, just sign up there and ...
+
+We are using `transifex <http://transifex.com/projects/p/leap-client>`_ to coordinate translation efforts. If you want to contribute, just sign up there and ...
 
 .. note::
    ... and what??
@@ -32,8 +30,9 @@ For devs: i18n conventions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. note::
-   should link to PyQt docs on i18n
-   also our special cases (labels and exceptions)
+   should say something about our special cases (provider labels and exceptions) when we get decision about it.
+
+Refer to `pyqt documentation <http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/i18n.html>`_.
 
 tl;dr;::
 
@@ -41,17 +40,64 @@ tl;dr;::
 
 for any string that you want to be translated.
 
+.. Note about this: there seems to be some problems with the .tr method
+   on QObjects. Investigate this.
+   I still believe we can use a generic _ method which is smart enough to
+   fallback to QObject.tr methods or lookup our own tr implementation (for our
+   multilungual objects, like in exceptions or provider labels that came from json objects).
+   --kali
+
 For i18n maintainers
 ^^^^^^^^^^^^^^^^^^^^
 
-.. note::
+You need ``pylupdate4`` for these steps. To get it, in debian::
 
-   how do we use the transifex client; automation.
+   $ apt-get install python-qt4-utils
 
 If you do not already have it, install the ``transifex-client`` from the cheese shop::
 
    pip install  transifex-client
 
+You can learn more about the transifex-client `here <http://help.transifex.com/features/client/index.html>`_.
+
+**1.** Add any new source files to the project file, ``data/leap_client.pro``. *We should automate this with some templating, it's tedious.*
+
+**2.** Update the source .ts file ``data/ts/en_US.ts``.::
+
+   $ make translations
+
+**3.** Push source .ts file to transifex::
+
+   $ tx push -s
+
+**4.** Let the translation fairies do their work...
+
+**5.** *Et voila!* Get updated .ts files for each language from ``Transifex``. For instance, to pull updated spanish translations:: 
+
+   $ tx pull -l es
+   Pulling new translations for resource leap-client.leap-client (source: data/ts/en_US.ts)
+   -> es: data/translations/es.ts
+   Done.
+
+
+Note that there is a configuration option in ``.tx/config`` for setting the minimum completion percentage needed to be able to actually pull a resource.
+
+**6.** Generate .qm files from the updated .ts files::
+
+   $ make translations 
+
+and yes, it's the same command than in step 2. One less thing to remember :)
+
+**7.** Check that the .qm for the language you're working with is listed in ``data/resources/locale.qrc`` file. That should take the translated files from ``data/translations``
+
+**8.** Re-generate ``src/leap/gui/locale_qrc``. This is the embedded resource file that we load in the main app entry point; and from where we load the data for the qt translator object::
+
+    $ make resources
+
+If you want to try it, just set your LANG environment variable::
+
+    $ LANG=es_ES leap-client
+
 
 Translating the Documentation
 ------------------------------
diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst
index 8de4a1eb..e5bf1fa8 100644
--- a/docs/testers/howto.rst
+++ b/docs/testers/howto.rst
@@ -141,6 +141,16 @@ Testing the packages
 ^^^^^^^^^^^^^^^^^^^^
 When we have a release candidate for the supported platforms (Debian stable, Ubuntu 12.04 by now), we will announce also the URI where you can download the rc for testing in your system. Stay tuned!
 
+Testing the status of translations
+----------------------------------
+
+We need translators! You can go to `transifex <https://www.transifex.com/projects/p/leap-client/>`_, get an account and start contributing.
+
+If you want to check the current status of the client localization in a language other than the one set in your machine, you can do it with a simple trick (under linux). For instance, do::
+
+    $ lang=es_ES leap-client
+
+for running  LEAP Client with the spanish locales.
 
 Reporting bugs
 --------------
diff --git a/docs/translations.txt b/docs/translations.txt
deleted file mode 100644
index 8cdb2e40..00000000
--- a/docs/translations.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Translations steps
-==================
-
-1. Use .tr() on labels to be translated.
-
-Note about this: there seems to be some problems with the .tr method
-on QObjects. Investigate this.
-
-I still believe we can use a generic _ method which is smart enough to
-fallback to QObject.tr methods or lookup our own tr implementation (for our
-multilungual objects, like in exceptions or provider labels that came from json objects).
-
-2. Add source files to the project file, data/leap_client.pro (Note: investigate if we can use some form of expansion here; it's tedious to add source files one by one).
-
-3. Still in data/leap_client.pro, add a translation per each language. Translations live in data/translations.
-
-4. exec ``pylupdate4`` data/leap_client.pro to generate initial .ts file
-5. Use QtLinguist (* or whatever web service we end up using *) to translate stuff. We expect the ts to follow Qt xml format, which seems standard enough to allow some fair degree of play.
-6. Execute ``lrelease data/leap_client.pro`` to generate .qm files.
-7. Check that the .qm for the language you're working with is listed in data/resources/locale.qrc file.
-
-8. Execute ``make resources`` to re-generate locale_qrc (in src/leap/gui). This is the compiled resource file that we load in the main app entry point; and from where we load the data for the qt translator object.
diff --git a/docs/user/install.rst b/docs/user/install.rst
index 22f88b12..1f0fd831 100644
--- a/docs/user/install.rst
+++ b/docs/user/install.rst
@@ -32,7 +32,7 @@ Get the code
 
 .. warning::
 
-   This... won't work either, as-is. This should be the third optional way to install stable releases from master branch. Right now that does not work because there is *nothing* updated in the master branch. Leaving this here since this is what we will be doing, but if you really intend to have a working tree, refer to the sections :ref:`setting up a working environment <environment>` or :ref:`fetching latest code <fetchinglatest>`.
+   This... won't work either, as-is. This should be the third optional way to install stable releases from master branch. Right now that does not work because there is *nothing* updated in the master branch. Leaving this here since this is what we will be doing, but if you really intend to have a working tree, refer to the sections :ref:`setting up a working environment <environment>` or :ref:`fetching latest code for testing <fetchinglatest>`.
 
 You can get the code from LEAP public git repository ::
 
diff --git a/docs/user/intro.rst b/docs/user/intro.rst
index fe983b63..abb6d487 100644
--- a/docs/user/intro.rst
+++ b/docs/user/intro.rst
@@ -74,7 +74,7 @@ All contributions should have these three points in mind.
 .. _`gpl3`:
 
 GPLv3 License
-------------
+--------------
 
 .. image:: gpl.*