Difference between revisions of "Translation"

Revision as of 15:58, 20 July 2006

See also: http://www.gnucash.org/trans/

HOWTO: Translating GnuCash
Last update: 2003-07-04
(updated 2005-11-24 by Derek Atkins to convert to SVN; updated --Cstim 03:58, 22 March 2006 (EST); updated 2006-07-20 11:58 EDT by Derek Atkins)

The concept of this document is to give you step-by-step instructions on how to update (or create if non-existant) language translations for the gnucash project. See Translation Status for the current status of the project with respect to translation contributions.

Any additions or corrections to this file should be sent to either Jon Lapham <lapham@extracta.com.br>, Christain Stimming <stimming@tuhh.de>, or directly to the gnucash-devel mailing list.

Mailing lists, IRC and web sites

GnuCash

Translators will probably find two gnucash mailing lists of interest. General use questions and answers are found on the gnucash-users mailing list, specific development questions go to the gnucash-devel list and your finished translation file are also sent to the gnucash-devel list.

To subscribe or view archives of these lists, go the the gnucash web site, and follow the links to the mailing lists: http://www.gnucash.org/en/lists.phtml

Another excellent place to get help is on IRC, as many of the developers hang out there and are eager to help.

The main gnucash web site is loaded with information: http://www.gnucash.org/

GNU Translation Project

The GNU Translation Project is another way to submit translations: http://www.iro.umontreal.ca/translation/ (old URL: http://www.iro.umontreal.ca/contrib/po/HTML/ )

This is an additional tool for translation teams to keep track of their translations and submit them. If you submit a translation to gnucash, you can either (a) send it to the Mailing List gnucash-devel, or (b) submit it to the Translation Project (TP). In both cases, the gnucash translation manager (currently Christian Stimming) will receive the translation and commit it to SVN. SVN is the definite state of translation that will be delivered in the releases.

If you choose (a), then you can outright ignore any message from the TP, or you can even notify the TP that your translation of "gnucash" is being handled "external" and not via the TP. If you have a look at http://www.iro.umontreal.ca/translation/registry.cgi?domain=gnucash you will notice that e. g. the German translation "de" is listed as external.

For a new translation team we would actually suggest (b), because the TP gives some additional convenience for retrieving and submitting translations. This includes: you don't have to deal with the gnucash source package unless you really want to; the po file is automatically format-checked on submission; the po file doesn't need to be sent to a mailing list.

Again, GnuCash will receive translation either way and commit them to SVN anyway. You can choose which one you like more.

General Translations

General information about how to approach the translation of software can be found here:

• http://l10n.kde.org/docs/translation-howto/index.html
• http://developer.gnome.org/projects/gtp/l10n-guide/
• http://developer.gnome.org/projects/gtp/resources.html

Get the source from SVN

As of October, 2005, GnuCash now uses Subversion instead of CVS. Click here for an introduction to subversion.

The first thing to do is to download the latest STABLE branch of gnucash from SVN and get it to compile. See Translation Status to choose which branch to use for translations. Do not use the trunk branch unless specifically mentioned in Translation Status. Because the text in the trunk branch changes so much it would be a waste of time to translate it. Do not worry, when the trunk branch becomes stable the existing translations in the STABLE branch will be merged. Your work will not be lost.

Checkout the current stable branch.

svn checkout http://svn.gnucash.org/repo/branches/2.0 gnucash

The argument "gnucash" above can be whatever you want your local directory to be called, and is optional. If you leave it out, you'll have a directory called "2.0" created containing all the source code.

Checkout the documentation (optional, but recommended)

svn checkout http://svn.gnucash.org/repo/gnucash-docs/trunk gnucash-docs

After this initial SVN checkout, you can update your SVN files using:

svn update

Compile & Install

Before starting to work on your translations, it is suggested that you compile the gnucash source code. This way you can get your system set up correctly with all the development packages you need. It is a good idea to actually run gnucash with your new translations because it is quite helpful to see the phrases in the context of the running program.

Enter the gnucash directory and run the autogen.sh script. This will generate the configure script. If it fails to generate the configure script then you are probably missing a bunch of development packages, like libtool gettext intltool automake autoconf, or any of the -devel packages that supply the various autoconf macros that gnucash requires. You will need to find the development packages for your system, install them, and then re-run autogen.

Note: there are some warnings that spew forth during autogen. Do not worry about them, apparently they are normal and can be ignored.

Once you create the configure script, you should run it. There are many options available when compiling gnucash, see the README.svn file for more information on the options. For now, we will just enable debugging and change the default prefix because these two changes will be handly later for tracking down problems and installing multiple versions.

cd gnucash
./autogen.sh
./configure --enable-debug --prefix=/opt/gnucash-svn

If configure complains about missing development packages, find them on your favorite OS distribution, install it, and try to re-run the configure command. Eventually, you should be able to get autogen to run without any error messages.

Next, compile gnucash:

make

To install (assuming "make" completed without any problems) you must be root.

su - 
make install

To compile the documentation, enter the gnucash-doc directory and go through the same process:

./autogen.sh
./configure --prefix=/opt/gnucash-svn
make
su -
make install

Running GnuCash

After installation, insure that it works by running (as a normal user, no need to be root here):

/opt/gnucash-svn/bin/gnucash

It is a good idea to use absolute paths like this to insure you run the proper gnucash executable. To run your OS pre-installed version of gnucash, usually you can type:

/usr/bin/gnucash

In either case, you can easily switch between the various languages the gnucash has available by placing the LANG env var before the call to the executable:

LANG=pt_BR /opt/gnucash-svn/bin/gnucash

The glossary file

Inside the po/glossary/ directory should be a "glossary" file for your language. This file contains a bunch of commonly used terms found in gnucash. It is recommended that you get this file translated first, and use it as a guide when translating the real .po file. Please keep in mind that this file will never be visible to a user! The glossary file is only a tool for you, the translator! I repeat: The strings from the glossary file will never be user-visible, they are only used by you, the translator.

Go into the glossary directory and rebuild your language's glossary file:

cd po/glossary/
./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot

If your .po glossary file does not exist, use this gnc-glossary.pot file to create it:

cp gnc-glossary.pot XXXX.po

If your .po glossary file does exist, use the msgmerge program to update it:

/usr/bin/msgmerge -o XXXX.po XXXX.po gnc-glossary.pot

Now, open your language's glossary file and translate it completely.

Contact the maintainer of your language

To find out who is the last person to work on your language, look near the top of the po/XXXX.po file which corresponds to your language. If your language does not have a .po file available, see the next section.

The beginning of your .po file should look something similar to this:

# Localization for Portuguese-Brazil
# Copyright (C) 2003 Free Software Foundation, Inc.
# Jon Lapham <lapham@extracta.com.br>, 2003
# Jose Carlos Nascimento - <joseca@psabs.com>, 2001.
# 
msgid ""
msgstr ""
"Project-Id-Version: GnuCash 1.8.3\n"
"POT-Creation-Date: 2003-05-16 16:42-0300\n"
"PO-Revision-Date: 2003-06-02 12:00-0300\n"
"Last-Translator: Jon Lapham <lapham@extracta.com.br>\n"
"Language-Team: NONE \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=ISO-8859-1\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=n != 1;\n"

Look to see who the "Last-translator" was, and send an email to that person and ask what you can do to help. This is important because if there already is an active maintainer of the translation file, you should interact directly with him or her. If there is no Last-Translator, or that person is not maintaining the file actively (and tells you to take over), you will become the maintainer and you should change the "Last-Translator" to your name and email address.

Build a new .po file

If there is no .po file for your language, then you can start a new one. Start by copying the file gnucash.pot into a work file named LL.po, where LL is your language code, and just edit this file. The first lines as shown in the previous section will contain several capitalized entries. Replace all the words in capitals with something appropriate. In this case, you will be the first author of the translation, and also the last translator of it. CHARSET may be UTF8 for example, and ENCODING is usually 8bit. Remove the `#, fuzzy' line once you have specified the items in capitals, because once this is done the header entry is no longer fuzzy.

Each message to translate is then given in turn in the PO file. For example, an untranslated entry might be:

#: lib/error.c:88
msgid "Unknown system error"
msgstr ""

The empty msgstr string has to be filled with the translation for the string shown after msgid. If you were a German speaker, say, the entry once translated might look like:

#: lib/error.c:88
msgid "Unknown system error"
msgstr "Unbekannter Systemfehler"

You just produce a translation for all entries in the PO file, one after another, respecting the overall file format and the quoting needed for special characters, when needed. Observation and intuition may allow you to grasp what the format should be; the precise rules for PO files are given in the GNU gettext manual. The msgfmt program is helpful for pinpointing formatting errors.

The top of the .po file should be edited somewhat. The comments at the top of the file should be changed to be current:

# Messages in Deutsch fuer GnuCash
# Copyright (C) 1999 Free Software Foundation, Inc.
# Jan-Uwe Finck <Jan-Uwe.Finck@bigfoot.de>, 1999.

Make sure that the header of your .po file contains this line:

"Plural-Forms: nplurals=2; plural=n != 1;\n"

...and that you change the "Last-translator" string to your name.

Initial processing of the translation file

Before you begin actual translation work, you should update the gnucash.pot file and use this to update your .po file. This process will insure that you have the latest translatable strings. In gnucash, a specific command at the top-level of the source tree will perform all necessary steps for this:

make pot

If your language file does not exist, see the previous section for creating a new language file.

If your language file does exist, update it using the msgmerge program:

/usr/bin/msgmerge -o LL.new.po LL.po gnucash.pot
mv LL.new.po LL.po

Translating the .po file

Finally. You are ready to do some translating!

Here is an example of translating some text into German:

Before:

#: messages-i18n.c:11
msgid ""
"The GnuCash personal finance manager.\n"
"The GNU way to manage your money!"
msgstr ""

After, the tranlation in the de.po file:

#: messages-i18n.c:11
msgid ""
"The GnuCash personal finance manager.\n"
"The GNU way to manage your money!"
msgstr ""
"GnuCash: Ihr persoenlicher Finanzmanager.\n"
"Der GNU-Weg, ihr Geld zu verwalten!"

You should read through every translation in the .po file at least once. If you translate a string that has the phrase "#, fuzzy" in the comments above it, remove the word fuzzy. A fuzzy translation means that the computer guessed what the translation should be.

After you finish translating, you should not have any "#, fuzzy" strings left.

For example:

#: messages-i18n.c:35
#, fuzzy, c-format
msgid ""
"There was an error writing the file\n"
"     %s\n"
"\n"
"%s"
msgstr ""
"Es gab einen Fehler beim Oeffnen der Datei. \n"
"     %s."

You need to correct the translated string and remove the 'fuzzy' keyword. For example:

#: messages-i18n.c:35
#, c-format
msgid ""
"There was an error writing the file\n"
"     %s\n"
"\n"
"%s"
msgstr ""
"Es gab einen Fehler beim Oeffnen der Datei. \n"
"     %s."

Notice that the comment "c-format" was not removed. That is correct, you should leave that.

When you see the comment "c-format", it means that the format codes in the tranlatable string are referring to C formatting codes. So, '%s' means text, '%d' means an integer, etc...

Current status

See Translation Status for the current status of the project with respect to translation contributions.

Disambiguation prefix

For future reference: It might be possible that gnucash will use "disambiguation prefixes" in msgids. Currently this is not yet the case, but here is an explanation: https://lists.gnucash.org/pipermail/gnucash-devel/2005-October/014236.html ; more explanation is also here: http://live.gnome.org/GnomeI18nDeveloperTips .

@Developers: In the normal source code of a gtk-based program, this feature is available by simply using the Q_( ) macro instead of the _( ) macro.

Testing and submitting your translations

You must check that your new translations are programatically correct (ie: that there are no unclosed quotes, etc). To do this, use the msgfmt program

/usr/bin/msgfmt -c --statistics XXXX.po

This will report any errors in your .po file if it finds them.

If you want to see your translations within a running version of gnucash, simply place your .po file in the po/ directory of your SVN copy of the gnucash source code (which you have previously installed) and from within the po/ directory type (you may need to be root to do this):

make install

Now you can run gnucash with your new translations:

LANG=XXXX /opt/gnucash-svn/bin/gnucash

Submitting

When you are happy with the new translation file, email a gzipped version of it to the gnucash-devel mailing list.

gzip XXXX.po

(email this file using your favorite mail client)

Alternatively, you can submit the finished translation via the GNU Translation Project. See the instructions on http://www.iro.umontreal.ca/translation/ and the first section of this document about how to do that.

See Translation Status for the current status of the project with respect to translation contributions.

Problems

intl/Makefile is already registered

When you see this error message during autogen.sh run:

configure.in:1219: error: `intl/Makefile' is already registered with
AC_CONFIG_FILES.
autoconf/status.m4:844: AC_CONFIG_FILES is expanded from...
configure.in:1219: the top level
autom4te: /usr/bin/m4 failed with exit status: 1
autoheader: /usr/bin/autom4te failed with exit status: 1
**Error**: autoheader failed.

Then you need to revert the configure.in script to the original form that is in SVN:

svn revert configure.in

Gtk-CRITICAL messages

Note: Fixing this problem is quite difficult. We keep the explanation here in case some developers need it in the future, but if you have no idea what we are talking about in the next sentences, you should rather ignore these Gtk-CRITICAL messages and our explanation here!

If you see any "Gtk-CRITICAL" messages while running gnucash, it is probably because you translated a string differently than how it exists in some other gnome library. You must discover which string you translated differently, and change the translation to exactly match that of the gnome libraries.

To do this, you need to run gnucash under gdb:

LANG=XXXX /opt/gnucash-svn/bin/gnucash-env gdb /usr/bin/guile

Then, from within gdb, issue:

run -e main -s /opt/gnucash-svn/libexec/gnucash/overrides/gnucash --g-fatal-warnings

Eventually, gnucash should crash (becuase of the --g-fatal-warnings directive), when it does, issue from within gdb:

backtrace

You should see some output that looks like this:

#0  0xffffe002 in ?? ()
#1  0x42028a73 in abort () from /lib/tls/libc.so.6
#2  0x4019d3d8 in g_logv () from /usr/lib/libglib-1.2.so.0
#3  0x4019d414 in g_log () from /usr/lib/libglib-1.2.so.0
#4  0x40500fdd in gtk_type_check_object_cast () from 
/usr/lib/libgtk-1.2.so.0
#5  0x407292e5 in gnc_mdi_tweak_menus (mc=0x825adb0) at gnc-mdi-utils.c:574
#6  0x40729d13 in gnc_mdi_child_changed_cb (mdi=0x8266fd8, prev_child=0x0,
     data=0x8265fd8) at gnc-mdi-utils.c:861

Notice position #5 which has "gnc_mdi_tweak_menus at gnc-mdi-utils.c:574"? Open that source file and find line 574:

573:  widget = gnc_mdi_child_find_menu_item(mc, "_View/_Toolbar");
574:  gtk_signal_handler_block_by_data(GTK_OBJECT(widget), info);

So, the problem is with the translation of "_View/_Toolbar". The "/" is a menu seperator, so you now know that the problem is with either the translation of "_View" or "_Toolbar". By switching to an English gnucash (LANG=C) and looking through your .po file, you should be able to find out the problem. Change the offending translation to whatever you see in the gnucash app. Remember that the translations must contain the proper underscores.

File accesses

To follow gnucash as it access files,

strace /opt/gnucash-svn/bin/gnucash

How to translate the GnuCash guide and/or help files

This section describes the actions needed to translate the manual.

First, you must *have* the gnucash-doc package installed. This is done as follows:

1. Checkout the documentation

svn checkout http://svn.gnucash.org/repo/gnucash-docs/trunk gnucash-docs

1. Create a new directory (if it doesn't already exist) in guide/<locale> where <locale> is something like es, en_GB, or pt_PT.
2. Copy the files from guide/C into this directory.
3. Recreate the image files in guide/C/figures so that they are appropriate to the locale.
4. Edit all the xml files and translate for the locale.
5. Test that your xml file has no syntax errors

  xmllint --valid --noout gnucash-guide.xml

To translate the help files, repeat steps 2-5 but replace the "guide" directory with "help".

For editing these DocBook xml files, various editors can be used; http://en.wikipedia.org/wiki/DocBook might contain pointers to some. People have said that OpenOffice has a plugin for DocBook available, in which case you could directly edit gnucash's xml files with OpenOffice. (FIXME: add precise description on how to get this here.)

How to translate the files containing the new account hierarchies

This section describes the actions needed to translate the files containing the new account hierarchies.

1. Create a new directory accounts/<locale>.
2. Copy the acctchrt_* files from accounts/C to accounts/<locale>
3. Do not change any xml tags.
4. In the directory accounts/, change the file Makefile.am and add your <locale> to the only line in that file.

For each file:

1. Change the gnc-act:title, gnc-act:short-description, and gnc-act:long-description to contain appropriately translated text. Do not add any newlines in the long description except at the end and begining of the string.
2. For each gnc:account in the file translate the act:name, and act:description fields. Please do not translate any other fields.

Note: You absolutely don't need to translate all of the files from accounts/C. A subset of those are fine as well. Probably several of them will not apply to your local legislative/economic system anyway. For a really customized account hierarchy you might better create a new account hierarchy file in GnuCash, and then, by hand-editing the xml code, split it up into several files and cut&paste the appropriate tags from the accounts/C/acctchrt_* files.

Thanks so very much to all the translators for their hard effort and excellent work.