TRANSLATIONS OF PICPUZ

The instructions here apply to the GUI interface (menus and dialogs).
For user guide translations, see below.

Translation files are normally as follows:
   /usr/share/picpuz/locales/picpuz-lc.po

"lc" is a standard 2-character language code, e.g. "de" for German, 
or a combination language and region code formatted "lc_RC", 
e.g. "de_AT" for Austrian German.

"lc" or "lc_RC" is also the locale of the target computer system, 
as shown by the following command: $ echo $LANG

The .po file contains the English phrases used by picpuz, with the
corresponding translations for language "lc" or language and region
"lc_RC". It can be edited with any text editor or one of the special
editors for .po files (e.g. poedit).

REVISE AN EXISTING LANGUAGE AND TRANSLATION

   1. Edit picpuz-lc.po to add or update translation strings.
   2. Open a terminal window and go to the location of the .po file.
   3. Compile the .po file to check for errors:
      $ msgfmt -v --check-format  -o /dev/null  picpuz-lc.po
   4. Run picpuz and check how the translations look.
   5. Send the modified .po file to me (kornelix2@gmail.com) 
      so it can be included in future releases.

Steps 2 and 3 are optional. The usual binary translation files (.mo)
that are output by msgfmt are not needed by picpuz. The translation 
source files (.po) are read directly by picpuz, and changes made to
a .po file are immediately effective. Steps 2 and 3 are useful to 
find errors (e.g. format codes in a translated string do not match 
those in the English string).

ADD A NEW LANGUAGE AND TRANSLATION

   1. Move the source program files *.cc and *.h from the release 
      tarball into some convenient directory.
   2. Create template files (.pot) from the source programs
         $ xgettext -s --keyword=ZTX -o picpuz.pot *.cc *.h
   3. Create translation files (.po) from the template files (.pot)
         $ msginit -l lc -o picpuz-lc.po -i picpuz.pot
      "lc" is the language and region code for the new language.
      If asked for an e-mail address, reply with Enter to ignore.
   4. Edit the .po file to insert translations for all text.
   5. Move the .po file to the installation directory:
         /usr/share/picpuz/locales/picpuz-lc.po
   6. Run picpuz and check how the translations look.
   7. Send the new .po file to me (kornelix2@gmail.com) 
      so it can be included in future releases.

PROBLEMS WITH LONG TRANSLATIONS

English can be terse compared to other languages (e.g. "undo" becomes 
"Rückgängig machen" in German), and this can cause ugliness in the 
GUI layouts. Therefore try to make dialog labels and buttons short.

CONTEXT DEPENDENT TRANSLATIONS

Sometimes the same English text will need multiple translations that
depend on context. A simple example is "save file" when used on a
toolbar button or in a menu. On the button the translation should be
short, but there is no limit for the menu. In German, this could be
"speichern" for the button and "in Datei speichern" for the menu.
The standard method to do this in Gnu gettext is fairly horrible, but
since picpuz reads the source translations (.po files) instead of
the binaries (.mo files), a simpler method is available. The English
text may include an extra string to distinguish different contexts.
This context string is removed from the GUI output, so the user does 
not see it. The context string is any short string followed with the
special marker "::". To continue our example, the picpuz-lc.po file
might look like this:
   msgid "save file"
   msgstr "in Datei speichern"
   msgid "toolbar::save file"
   msgstr "speichern"
In English, picpuz would show "save file" for both cases, and in 
German "in Datei speichern" or "speichern".

USER GUIDE TRANSLATION

The user guide is normally found here:
   /usr/share/doc/picpuz/userguide-lc.html

The file is a text HTML file, which may be edited with any HTML editor.
"lc" (or "lc_RC") is the language code or language and region code. 
The user locale in $LANG or $LANGUAGE is used to find "lc_RC". If a 
file with the region code is present, this file is used, otherwise the 
standard language version is used. If this is not found, the english 
file (userguide-en.html) is used.

If you make a new or revised translation, please send it to me so that
it can be included in future releases (kornelix2@gmail.com).


