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/gui/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 https://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"). You can also use ngettext if need be.
In .ui files, #include "gui/qtgettext.h" first in the .h file (see MainWindow.h).

   $ make clean && qmake CONFIG+=experimental && make

Then run the script to scan the source files, and regenerate .pot & .po files.
You'll need itstool (http://itstool.org/) installed.

   $ ./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

Message Context:
================

Some messages need a different translation, depending on the context
of the message. To enable translators to use different translation for
the same english message, context can be used.

Typically short messages tend to need context more often then long messages.
There is no need to add a context preemptively, please wait until a specific
need arises.

Please note that message context should follow some constrains:
   - message context comes at some performance penalty
   - Keep the context name short
   - try to pick a context name that is unlikely to change
     (changing the context name requires the translates to update the translation)
   - do not abuse the message context as a comment

The first parameter of _(msgid, msgctxt) and q_(msgid, msgctxt) is the
message itself.
The second parameter of _(msgid, msgctxt) and q_(msgid, msgctxt)
respectively is the message context.

Note that msgid and msgctxt are swapped compared to pgettext.

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

