[TYPO3-doc] Translating documentation

[Xavier Perseguers]

Hi,

As I recently tested to translate a documentation I did, I'd like to
share my experience.

My project is organized like that, prior to translating it:

.
|-- build
|-- source
|   |-- Part1
|   |   |-- Chapter1
|   |   |   |-- Subchapter1.rst
|   |   |   `-- Subchapter2.rst
|   |   `-- Chapter2
|   |       |-- Subchapter1.rst
|   |       `-- Subchapter2.rst
|   |-- Chapter2
|   |-- index.rst
|   `-- conf.py
`-- Makefile

I guess you get the point.

My index.rst basically is like that:

-------------
#################################################
Part 1
#################################################

Chapter1
########

.. toctree::
        :maxdepth: 1

        Part1/Chapter1/Subchapter1
        Part1/Chapter1/Subchapter2

Chapter2
########

.. toctree::
        :maxdepth: 1

        Part1/Chapter2/Subchapter1
        Part1/Chapter2/Subchapter2
-------------

I used this page as guide for localization my document (which is in
English as main language): http://sphinx.pocoo.org/latest/intl.html

I wanted to use Virtaal and not Pootle on my local computer.

1) Generate the gettext files

$ make gettext

This creates a directory "build/locale" which by default creates a big
.pot file for each "part" => Part1.pot and Part2.pot. These are pure
text files with all titles, and paragraphs of text (at this point I
don't know how to "translate" images and index entries).

2) Open Part1.pot in Virtaal (0.7.1 on Mac OS X, 0.7.0 is just buggy and
useless). Translate and save the file (Part1.po - without "t" which
stands for "template") to ./translated/source/fr (translated being next
to source and build).

3) Compile the file as a .mo and store it in

./translated/fr/LC_MESSAGES/Part1.mo

$ msgfmt translated/source/fr/Part1.po -o translated/fr/LC_MESSAGES/Part1.mo

4) Edit file source/conf.py:

a) Add a reference to the base directory holding translations:

locale_dirs = ['../translated/']

(../ because "translated" is at the same level than "source")

b) Search for the "language" directive which should be commented out:

# language = None

change it to

language = 'fr'

5) Compile your documentation as usual (make html / make latexpdf / ...)

Problems
------------------

Whenever the main document (in English) is modified, when you extract
the texts with "make gettext", you get a new .pot file which should be
merged with the existing translations (which is not stored in build/
because this directory may easily be cleaned-up with a "make clean").

Pootle handles that properly by allowing an uploaded file to be merged
with existing translations, marking changes in source as "dirty" =>
somehow forcing the translation to be adapted (a "hint" actually).

I created such a script as a PHP command line file which takes a .pot
and an already processed .po and merges the changes in the .pot into the .po

I'm now trying to use a Pootle virtual appliance freely available from
http://bitnami.org/stack/pootle to extend my experience with reST and i18n.

Cheers

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org