OpenSCAD human language translation
===================================

We use the GNU gettext system, both for c++ code as well as QT's .ui files.
The latter is accomplished by the '-tr' feature of QT's uic to insert
a gettext wrapper into the ui_xxxxx.h files. 

For somewhat similar designs, see the source code of projects like celestia, 
stellarium, licq, merkaartor, etc (although they typically use cmake).

Currently the build system does not auto-update anything. The .mo files must
be generated by running the gettext tools: xgettext, msgmerge, and msgfmt.
There is a script included, translation-update.sh, that automates this process.

File layout:
============

 ./locale/*.po - .po files, one per language
 ./locale/openscad.pot - .pot template, generated by xgettext
 ./locale/POTFILES - list of source files with translatable strings (generated)
 ./locale/LINGUAS - list of language codes for which .po files exist
 ./src/qtgettext.h - wrapper code between QT and GNU gettext
 ./scripts/translation-update.sh - simple unix helper script
 ./locale/xx/LC_MESSAGES/openscad.mo - 'binaries' of .po files, built by script

To translate the strings:
=========================

Use a text editor or special program (poedit or lokalize) to edit the .po file.
( See http://en.opensuse.org/SDB:Localization_work_with_po_files )
Then submit your new .po file as an OpenSCAD github issue or pull request:

https://github.com/openscad/openscad/issues/ 

In the future there might be a site to allow translations in a browser:

https://translations.launchpad.net/openscad 

If all else fails, email the OpenSCAD mailing list with your new .po 
file attached.

To make source code changes:
============================

In .cc files, #include "printutils.h" and change each "text" into 
_("text"). In .ui files, #include "qtgettext.h" first in the .h file 
(see MainWindow.h). Then clean and rebuild to recreate the ui_xxxx.h 
files.

   $ make clean && qmake && make

Then run the script to scan the source files, and regenerate .pot & .po files.

   $ ./scripts/translation-update.sh

This will create new .po files with any new untranslated strings you 
added to the source code. These .po files can be distributed to 
translators for translation. After the translated .po file is obtained, 
overwrite the old .po and run the same script to update the .mo files.

   $ ./scripts/translation-update.sh

To add a new language:
======================

First add the language code to file ./locale/LINGUAS. Then run msginit,
replacing $LANGCODE with the language code you want. 

    $ msginit -l $LANGCODE -o ./locale/$LANGCODE.po -i ./locale/openscad.pot

You will now have a new ./locale/xx.po file to edit and translate

Testing:
========

On unix, set the locale related environment variables. For example in 
French, run this:

   $ LANGUAGE=fr ./openscad

Linux system trace tools can help find errors. To show open()s on .mo files:

   $ LANGUAGE=fr strace -f ./openscad 2>&1 | grep LC_MESSAGES