Internationalisation/Offline/Details
1. Download and install gettext. Linux users should try to install it using their distributions package management (like rpm, dpkg, apt, ...). Windows user download gettext from http://gnuwin32.sourceforge.net/packages/gettext.htm. Both make sure, that the gettext binaries are in your PATH environment variable.
Note for Windows users: If you installed the gettext binaries into e.g. C:\Program Files\GnuWin32, then you need to add C:\Program Files\GnuWin32\bin; to the existing PATH environment variable: Control Panel → System → Environment Variable (Tab Extended) OR run the following command in a windows command shell: set PATH=%PATH%;C:\Program Files\GnuWin32\bin;.. Windows XP and Windows 2000 are currently supported.
2. All targets related to internationalisation and localisation issues are part of 
build-i18n.xml. To create PO-template files, run ant -f build-i18n.xml update-pot. All LANG.po files (which contain the translation and are maintained by the translator himself) are updated with ant -f build-i18n.xml update-po. To create the final message catalogs, run ant -f build-i18n.xml update-catalog.
3. To create a translation in your language, go to src/org/jmol/translation/Jmol (for the application, respectively src/org/jmol/translation/JmolApplet for the applet) and copy Jmol.pot (resp. JmolApplet.pot) to Jmol-LANG.po (resp. JmolApplet-LANG.po) - LANG means your language code: e.g. de for German, fr for French and so on.
4. To begin your translation, open the newly created Jmol-LANG.po or JmolApplet-LANG.po files with an editor of your choice - Windows users be aware, that the editor MUST NOT add any control characters (like e.g. Word does)!. There are also specialised editors for this work: e.g. poedit, kbabel, or gtranslator.
5. The opened file will look like this:
# SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER # This file is distributed under the same license as the PACKAGE package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. #
These lines are comments. Adjust them and add a descritpive title, the right copyright and your name as author. Be aware, that lines beginning with #, or #: have a special meaning and are not normal comments.
#, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: jmol-developers@lists.sourceforge.net\n" "POT-Creation-Date: 2005-06-01 02:02+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <LL@li.org>\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n"
We call this part the po-headers. The line #, fuzzy says, that the headers are outdated. Customise "Project-Id-Version: PACKAGE VERSION\n", "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n", "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" and maybe "Language-Team: LANGUAGE <LL@li.org>\n" (if you don't belong to a language team, then write none) and remove the fuzzy comment. In every case make sure, that Content-Type and Content-Transfer-Encoding are right (if possible, use UTF-8).
If you plan to use poedit to do the translation, you can add several lines to the headers (replace LANGUAGE and COUNTRY).
"X-Poedit-Language: LANGUAGE\n" "X-Poedit-Country: COUNTRY\n" "X-Poedit-Basepath: ../../../..\n"
Then begin the "real" translation:
#: org/openscience/jmol/app/AboutDialog.java:57
#: org/openscience/jmol/app/GuiMap.java:155
msgid "About Jmol"
msgstr ""
#: org/openscience/jmol/app/AboutDialog.java:67
#: org/openscience/jmol/app/HelpDialog.java:77
#: org/openscience/jmol/app/WhatsNewDialog.java:68
#, java-format
msgid "Unable to find url \"{0}\"."
msgstr ""
[..]
A line or block beginning with msgid contains the untranslated (or original) string inside double quotation marks. Above this line, you see the location entries #: path/to/file.java:line (where the string can be found in the source) and sometimes some special comments #, java-format or #, fuzzy or even #, fuzzy, java-format (telling you more about the format of a string or the state of a translation) - these lines are added and changed automatically by running ant -f build-i18n.xml update-po. Place your translation into the line or block beginning with msgstr and inside double quotation marks.
6. After finishing, add your translation (Jmol-LANG.po) and JmolApplet-LANG.po to Jmol SVN and your language code to property all.Jmol.languages and all.JmolApplet.languages in build-i18n.xml.
7. At the end of this short howto, we should speak about special situations and a few hints, you should consider:
- double quotation marks inside a string must be escaped with a backslash: msgstr "... \" ..."
- single quotation marks must be doubled (two single quotation marks) for Java texts (#, java-format)
- #, fuzzy means that the translation string is outdated (e.g. the original string changed) - in this situation, check your translation and adjust it if necessary - then you can remove the fuzzy string (e.g. line #, fuzzy, java-format becomes #, java-format)
