.. _documentation_translation:

*******************************************
How to Help Translate the Documentation
*******************************************

:Author: Yves Jacolin
:Contact: yjacolin at free dot fr
:Last Updated: 2014-04-16

.. contents:: Table of Content
	:depth: 2
	:backlinks: top

Introduction
*************

This chapter aims to explain how to help translating the documentation into 
another language than English. Some languages are already enabled for translating 
and some are not. Pleas see :ref:`documentation_translation_newlang` if 
needed.

This chapter is still being written. Please forgive any errors you find here 
and please report them to the mapserv-dev list with a [doc] flag in the subject. 

The translation process has several steps:

* create a language in Transifex
* add the new language into the source repository
* add new translator to the language group in Transifex
* translate each chapter
* pull each translated files into the language dir from Transifex 
* and push them into doc repository
* build the documentation

This chapter describes how to add a new language, how to join a language group, 
and how to translate the documentation.

What is Transifex for?
***********************

Transifex is a croudsourcing translation web application. It allows projects to 
let people easily translate documentation, websites, and applications.

It offers a graphic interface for those of you who don't like command line but also 
some features for those who love them.

Transifex helps the translator to improve their translation with suggestions, glossary 
and proofreading process.

Starting with Transifex
************************

Subscribe to Transifex
-----------------------

You need to subscribe to Transifex before translating. Go to `Transifex subscribing page <https://www.transifex.com/signup/contributor/>`_ and create a new account.

.. image:: ../images/documentation/tr_newaccount.png

If not already done, please login ;)

Find the project
----------------
There are several OSGeo projects hosted on Transifex, here are some of them:

* `MapServer <https://www.transifex.com/organization/mapserver/dashboard>`_
* `PostGIS <https://www.transifex.com/organization/postgis/dashboard>`_
* `QGIS <https://www.transifex.com/organization/qgis/dashboard>`_

You can find more in the Transifex website.

Each project has a news page to send some information to you, so please, take 
some time to read them. You can also send some messages to others to discuss on 
a topic.

Ask to join a translator group
------------------------------

Click on the link to access the dashboard of the MapServer project in Transifex (link above), 
then the language you want to join and finally find the button *Join team*. You 
should now wait for the manager accept you in the group (given them time to read 
your request, some of them could not have so much time).

.. image:: ../images/documentation/tr_jointeam.png

Welcome to the translation team!

.. _documentation_translation_newlang:

Request a new language
**********************

For the MapServer project, asking a new language will add a new language group on Transifex 
and some stuff in the documentation repository. Don't need to ask on the mapserv-dev 
list (but we will be happy to receive some message or feedback from you).

Go to the MapServer dashboard on Transifex (see link above) and click on 'Request language':

.. image:: ../images/documentation/tr_newlanguage.png

Creating a new language by the manager should not be too long, actually as long 
as to accept you in the team.

Translation Process
*******************

Describing the translation process could be an awesome task, so we are just going 
to describe the short way and we let you discover all the features in Transifex.

Choose a file and translate
----------------------------

You are now formally a translator of the MapServer project on Transifex. So you 
should go to the dashboard of the project, choose your language:

.. image:: ../images/documentation/tr_chooselang.png

Then select a file in the new interface:

.. image:: ../images/documentation/tr_choosefile.png

The new interface allow you to choose a string to translate - the toolbar allow you 
to filter untranslated or Unreviewed string:

.. image:: ../images/documentation/tr_translatingui.png

Clic on the string on the left, translate it where 'Type your translation here' 
appears in the screenshot above. When finished clic on *Save*. Suggestion or 
glossary appear sometime on the right panel to help you.

In the untranslating string field, you have severa tools:

* Duplicate : copy past the english string into the translated file (sometim used 
  to let the translator easily duplicate identical string).
* Machine translation : never used, so I can't help on this ;)
* Revert : revert your translated string.

You have some keyboard shorcut:

* Tab : switch to new string and save your modification
* Alt-Shif D : review the string and go to the next string

Clic on the Shorcut button to the right to find:w
much more keyboard shorcut.

Proof reading
--------------

Proof reading is similar to the translation process, except that you should be 
a reviewer to do it and you should click on the *Review* button instead of 
the save button.

Please don't review the string you translated or wait for some time before 
to be sure that you don't miss some errors.

Other features
***************

Glossary
---------

Suggestion
------------

FAQ
****

Why don't I see my translation into the MapServer website?
-------------------------------------------------------------

We need to push your translation into the doc repository then build again the 
documentation. This is not an automatic task so there is some delay between 
your file editing and the time where you can see them in the website.

You can send an email to the mapserver-dev list to ask for someone to do the 
pull/push process for the translation.

