History

Some information on this page seems to be outdated .. This page should be revised (12.Dec.2012)

Introduction

These pages provide details of everything you need to know relating to the QGIS documentation translation effort including checking out, compiling, translating and procedural details. It is managed by the Manual Translation Team Lead. If you plan to translate the manual into a foreign maybe not yet existing language and for any other related questions, please write to the qgis-community-team mailing list.

Mailing List

A (currently low volume) mailing list is available for discussion of both, translation of the QGIS user interface and documentation (User, Compilation and Coding Guide) issues. We strongly encourage anyone joining the documentation effort to join this list!

The Documentation Process

The documentation process works in the following way. In the build up to each release the master document (in english) is updated. When this document is complete and we are absolutely sure there will be no more changes to the application ('code freeze') the documentation in subversion will be tagged and branched for translation into several foreign languages.

- branches||
|   `-- 1.6.0|
|       |-- italian|
|       `-- german|
|       `-- etc...|

Document writers will be given write access to their branch and the translation process can commence. The table in the next section can be used to give a macro level view of how you are in the translation process. If you read on, we will explain how to get the docs from SVN in more detail.

Translation Maintainers

Note: The QGIS project is looking for people who are willing to invest some more time - even perhaps to coordinate the documentation translation effort. We are trying to improve our project management process and spread the load more evenly between people who each have a specific area of resposibility, so any contribution you have to make will be greately appreciated.

Please add your details to the list below. If you would like to nominate yourself as a coordinator for a language please go ahead. If more than one person nominates themselves as coordinator for the same language, please contact each other and resolve how you will manage your efforts.

*Translation Coordinators of QGIS User Guide

Language Coordinator, Additional Contributors Email wiki page to manage translation
Dutch Diethard Jansen diethard.jansen at gmail.com Manage Manual Translation Dutch
Richard Duivenvoorde
Willem Hofmans
Theo Buijtenhek
French Jean Roc MORREALE jr.morreale at enoreth.net
Coffres-Forts et Armoires fortes http://www.infosafe.fr
Yves Jacolin yjacolin at free.fr
Sebastien Vial sebastien.vial at gmail.com
Ludovic Granjon ludovic.granjon at free.fr
Jeremy Garniaux jeremy.grx at gmail.com
Patrice Vetsel ubuntu at kagou.fr
Mayeul Kauffmann Mayeul (point) Kauffmann (chez) free point fr
German Otto Dassau dassau at gbd-consult.de
Greek Stefanos Anastasiou emperor_stef at yahoo.gr
Korean Sanghee Shin shshin at gaia3d.com
Italian Paolo Cavallini cavallini at faunalia.it
Giuseppe Patti geognu at infinito.it
Polish Robert Szczepanek robert at szczepanek.pl
Andrzej Swiader andrzej.swiader at uj.edu.pl
Brazilian Portuguese (PT_BR) Arthur Nanni
Portuguese (PT_PT) Giovanni Manghi giovanni.manghi at faunalia.pt
Vânia Neves vania.neves at faunalia.pt
Russian Alexander Bruy alexander.bruy at gmail.com
Denis Rykov rykovd at gmail.com
Maxim Dubinin sim at gis-lab.info
Spanish Grupo GNU Linux Universidad Distrital glud at udistrital.edu.co
Axel Moser moser.axel at gmail.com
Juan Manuel Carrillo juancho126 at gmail.com
Paulo César Coronado paulo_cesar at udistrital.edu.co
Mario Pisa mario.pisa at gmail.com

How to become a maintainer

There are currently some restrictions to check out the QGIS documentations with write-support. If you like to help with the translation of the current QGIS manual please write to the qgis-community-team mailing list. and contact the current language coordinator listed above.

What you need to get started

Following steps are needed to get write-access to the documentation repository.

  • LaTeX (tetex and tetex-extra on debian-based systems)
  • convert from the image-magick-package
  • subversion client
  • Read more about subversion here: http://svnbook.red-bean.com/
  • latest QGIS version
  • some time to contribute to the manual :)

Further you need to decide on a username and password. You will be given access to write to the documentation translation branch for your chosen language.

Translating the english documentation

Translating the latex sources inside the svn branches (translation areas) is pretty simple. To contribute directly you need a valid username with password and a subversion installation on your PC. You can write to the qgis-community-team mailing list. The Manual Translation Team Lead help you and organize everything you need and create a translation branch for the language you want to translate the english latex files into.

Structure of the translation repositories

The folder structure looks like this (3 levels deep):

- branches||
|   `-- 1.5.0|
|   `-- 1.6.0|
|       |-- italian|
|       `-- german|
|       `-- spanish|
|       `-- ...|

Checkout a translation branch

Once your account has been set up you are able to check out the translation branch as a named user. For a clean checkout you need a svn-client. The following procedure is written for GNU/Linux to access to the documentation repository:

# Checkout as a guest
svn co https://svn.osgeo.org/qgis/docs/branches/1.6.0/<language>

# Checkout as a named user
svn co --username <your username here> https://svn.osgeo.org/qgis/docs/branches/1.6.0/<language>

Editing and Building

Before you start translating content you should update your local working copy with the latest copy of the SVN-server. This is necessary, because another person might have updated the SVN-server with his/her latest work:

cd branches/1.6.0/<language>/user_guide
svn update

Now xou can start with the translation of the .tex files with your favorite text editor. To build the translation as a PDF-doc, change into the folder user_guide and do the following:

cd branches/1.6.0/<language>/user_guide
make
make pdf

when finished you need to commit (upload) your changes as soon as possible to prevent that work is done twice by another person. Inside the folder user_guide type:

svn commit

Windows

For Windows a nice SVN-client is Tortoise SVN which integrates smoothly into the windows explorer. All needed SVN-commands described above can be used inside the explorer using the context-menu. Find more information at the Support Page.

For using LaTeX with windows it is recommended to use the MikTeX distribution located at MikTeX Page. There are also several LaTeX-Editors available for windows like
Winshell
TeXMaker
TeXnicCenter if you like WYSIWYG editing (mostly you loose some advantages of LaTeX) you can use
LaTeXEditor or for a 28day free period
BaKoMa TeX

Some hints translating the latex files

  • All you need to translate is the english text within the files ending with .tex (e.g. map_composer.tex).
  • You don't need to adapt or change the images nor the names of the images.
  • You can ignore all commands starting with \ (e.g. \section) and only translate the text inside the brackets (e.g. \section{Introduction} becomes in german \section{Einführung}).
  • For figures you can also almost ignore most of the definition and only translate small parts (see the example below):
\begin{figure}[ht]
<pre>
   \begin{center}
   \caption{Image of a blank Map Composer}\label{fig:map_composer_blank}\smallskip
   \includegraphics[clip=true, width=\textwidth]{map_composer_blank08}
</pre>
\end{center}
\end{figure}
in german becomes:
\begin{figure}[ht]
<pre>
   \begin{center}
   \caption{Bild eines leeren Map Composer}\label{fig:map_composer_blank}\smallskip
   \includegraphics[clip=true, width=\textwidth]{map_composer_blank08}
</pre>
\end{center}
\end{figure}
  • To check the translation you can build the latex sources simply with 'make'.

Problems with cyrillic and their solution

During manual translation to the cyrillic language you may encounter some problems (found during translation manual into Russian and Ukrainian).

First problem: after translation building latex sources fails with error

! Package inputenc Error: Unicode char \u8:? not set up for use with LaTeX

This is because Cyrillic encodings are T2A, T2B and T2C not T1 which is used by default. So you need to modify qgis_style.sty. Find string
\usepackage[T1]{fontenc}

and replace it with
\usepackage[T1,T2A]{fontenc}

Another problem - after translation section titles are not displayed in Table of Contens, they are replaced with empty strings. To fix this you need to edit
qgis_styles.sty again. Find line

\usepackage[bookmarks=true, pdftitle={QGIS User Guide}, pdfauthor={QGIS Project}, pdfsubject={QGIS User Guide}, breaklinks=true, colorlinks=true, linkcolor=blue, urlcolor=red]{hyperref}

and modify it (add "unicode" in square brackets)
\usepackage[unicode, bookmarks=true, pdftitle={QGIS User Guide}, pdfauthor={QGIS Project}, pdfsubject={QGIS User Guide}, breaklinks=true, colorlinks=true, linkcolor=blue, urlcolor=red]{hyperref}

May be in future this fixes will be included in manual.

For any questions you can get help from the qgis-community-team mailing list.

First notes for the new translation workflow, based on rst / gettext

In the new documentation framework, we are going to move from LaTeX to rst format.
This is a very schematic representation of the translation workflow in the new framework:

  • the master document (EN), in rst format, is created/updated and committed to git
  • the administrator creates/updated the .pot files and then creates/merges the .po files for each translation (the Sphinx customized Makefile provides builders for doing this)
  • the translators can now update the .po files online using the web application (based on Pootle) or offline using one of the several translation file editors desktop tools (or even vim, gedit...)
  • as soon as the translator completes the translation, she/he should commit the changes to git (this way it is reduced the possibility of conflicts)
  • on the server there will be a scheduled job in crontab that will compile the messages and build the Sphinx documentation for master (EN) and for each language. A copy of the documentation for master (EN) and for each language will be kept also for any QGIS release tagged in github

desktop based translation file editors

web based translation file editors

Note that the Pootle offline editing documentation page gives nice hints related to the offline editing process.