Difference between revisions of "Translation"

Revision as of 14:21, 25 December 2010

HOWTO: Translating GnuCash

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.

1 Mailing lists, IRC and web sites
2 Get the source from SVN
3 Compile & Install
4 Running GnuCash
- 4.1 Changing the Language on Windows
5 Naming Convention
6 The glossary file
- 6.1 Terms missing or inadequate in the glossary file
7 Contact the maintainer of your language
8 Initial processing of the translation file
9 Build a new .po file
10 Translating the .po file
11 Testing and submitting your translations
- 11.1 Submitting
12 Problems
13 How to translate the Windows Installer
14 Check doc/README-*
15 How to translate the GnuCash guide and/or help files
16 How to translate the files containing the new account hierarchies
17 How to translate the website
18 Tips for Developers

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 using the internet relay chat 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://translationproject.org/

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 managers (currently either Cristian Marchi or Christian Stimming) will receive the translation and commit it to gnucash's 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. In that case the TP would ask you to notify the TP that your translation of "gnucash" is being handled "external" and not via the TP. If you have a look at http://translationproject.org/domain/gnucash.html you will notice that e. g. the German translation "de" is listed as external.

As a translator or translation team, you can also choose method (b). In this case you should follow the instructions on the TP website http://www.translationproject.org as for how to join your language translation team and for how to submit your translated po file. The TP probably gives you some additional benefit 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.

The only problem is, that as the upstream coordinators, we cannot easily update the pot template which is stored at the TP. Instead, it will be updated only if we release a new version of the gnucash package. As a workaround, the TP suggests we can "release" a pre-version which is only sent to the TP and nowhere else (like a gnucash-2.3.15-pre1), but we never liked that solution because those "pre-"packages always get confused with the "real" ones. In the meantime, our conclusion is that it is not possible to update the pot at the TP at will, only at release time. [1]

(Some historical explanation: During 2006/2007, the TP was paralyzed by a long period of inactivity, which was rather disappointing for anyone trying to use it. In mid-2007 a new maintainer took over, and by then the TP should have been a convenient way of handling translations again. Unfortunately, by the end of 2007 the TP maintainer at that time, Benno S., got angry about the way GnuCash accepts submitted translations and refused to handle translations for GnuCash anymore. Subsequently, the TP maintainers changed and with the new maintainers, any disagreements were resolved completely and the cooperation resumed just fine. Since Summer 2009 the TP handles translations for GnuCash again. Please feel free to start using it and tell us about your experience.)

Again, GnuCash will receive translations either way and commit them to SVN anyway. Directly mailing it to the mailing list might make your translation arrive a bit faster, but either way works fine.

General Translations

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

Other Useful Sites

There are many online dictionaries, use a search engine like google, to find the best fitting.
Comparing articles on wikipedia in your language and english can be helpful.
In special cases the terminology database of the European Union Inter Active Terminology for Europe can be used, too.

Get the source from SVN

GnuCash uses Subversion as a repository server. Click here for an introduction to subversion. Alternatively you can also use Git; look there for the equivalent commands.

The first thing to do is usually, 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/gnucash/branches/2.2 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.2" created containing all the source code.

Update spring 2009: As mentioned on Translation Status, current the translation work should indeed be done on the trunk branch, which you can checkout as follows

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

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 later 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.

autogen.sh

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.

configure

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. See your local copy of the README.dependencies file for library dependency notes. Also check out the dependencies page. Eventually, you should be able to get autogen to run without any error messages.

make

Next, compile gnucash:

make

make install

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

Changing the Language on Windows

If you are running GnuCash on Windows, you can set the interface language by editing the file "gnucash.cmd" in the folder "C:\Program Files\gnucash\bin" (or wherever you installed GnuCash into). If you want to change the default language to English, you should add the line:

set LANGUAGE=en_US
set LANG=en_US

The "gnucash.cmd" file should look similar to the text below.

set PATH=C:\Program Files\gnucash\bin;C:\Program Files\gnucash\lib;C:\Program Files\gnucash\lib\gnucash;%PATH%
set GUILE_WARN_DEPRECATED=no
(...)
set LTDL_LIBRARY_PATH=C:\Program Files\gnucash\lib
set LANGUAGE=en_US
set LANG=en_US
start gnucash-bin

Naming Convention

The language code is of the following form:

<language>[_<COUNTRY>[.<Charset>]]

using the well known ISO codes 639-1 for languages and 3166-1 for territories.

If you are the first translator for your language, you should name your files and directories only with your language code. So all people using your language despite of their country will benefit from your work.

If there are parts, which are specific for your country, e.g. business account templates respecting local law, then they should be in a <language>_<COUNTRY> directory.

The common charset in gnucash is utf8, but there might be issues in MS Windows specific parts. [FIXME: Still existent?]

In the following parts of this document 'XXXX' and 'LL' refer to your language code.

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.

Terms missing or inadequate in the glossary file

If you detect an important term which is missing or could be better explained, open a bug and add a patch for the source file gnc-glossary.txt. The - with the exception of the headline - alphabetical sorted lines of this file have the form:

Msgid<TAB>Comment

To test it, run the following steps after you changed gnc-glossary.txt:

./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot will generate a new gnc-glossary.pot,
run above msgmerge command for your XXXX.po and check it for the new msg,
if successful, update all *.po files with:

find *.po -exec /usr/bin/msgmerge -o '{}' '{}' gnc-glossary.pot \;

check and translate the new string in your new glossary file.

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.

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 make complains "make: *** No rule to make target `<path/to/missing-source-file>', needed by `gnucash.pot'. Stop.", you should run

make clean

and then retry "make pot". That can happen because we sometimes remove obsolete files.

Now go in the po directory:

cd po

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

If your language file does exist, update it using the msgmerge program. This will move the old translations of unchanged strings in the new file:

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

If there are more persons working on your language, it is a good idea to create now a preparing patch containing only the "noise" from the updated pot file. Then the others can later read your real work much easier.

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 an adjusted form, e.g. for slavian languages set nplurals=3, of this line:

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

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

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 translation 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 there is no translation. The computer took some guess about what the translation might be, but as long as it is marked "#, fuzzy", this guess will simply be ignored and this string will stay untranslated. A string marked as "fuzzy" means it will not be translated in the program.

After you finish translating, you should not have any "#, fuzzy" strings left. Remember, a string marked as "fuzzy" means it will not be translated in the program.

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, because only then the translation will actually appear in the program. Remember, a string marked as "fuzzy" means it will not be translated in the program. 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 Schreiben 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 translatable 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.

To see some statistics how many strings are translated, you can run

for i in *.po; do echo -n "$i:"; msgfmt -c --statistics $i;done

in your po directory.

Tools

Additional Tools: You can use Poedit ( get it here: http://www.poedit.net/download.php ) to finish the PO file edit and build.
KBabel is another recommended tool
Lokalize is the successor of KBabel in KDE4
Emacs has the po-mode to edit po files
GTranslator is another tool but we recommend not to use it because the version of 2006 doesn't support all of the interesting elements inside the po file.

(feel free to add more tools here)

Priority

As you might have noticed, the po file for GnuCash is rather big by containing almost 4000 strings. It is somewhat helpful to look into different priorities for the different strings there. However, unfortunately the po file format doesn't enable any easy way for the GnuCash project to make the import strings differently from the less important ones. However, for a few files the developer team can give you some guidelines for the general priorities.

The source code location of a string gives you some hint about its priority. In particular, the following file suffixes or file locations imply a certain priority:

High Priority: Strings from all *.glade.h files will appear in the GnuCash user interface (UI) somewhere for the user. This may imply a somewhat higher priority to those strings - however, some UI elements are rarely used, so the actual location of the .glade file has an influence as well, but there isn't an easy rule for that anymore.
Low Priority: Strings from all *.schemas.h files will not appear in the gnucash UI. Instead, they are shown only inside the gconf-editor program when the user wants to set particular gconf keys of GnuCash. You can safely consider the .schemas.h strings with lower priority than the others.

Unfortunately, there is no such simple rule for strings from *.c files or the single large intl-scm/guile-string.c file. The strings from there may be of higher or lower priority, but this isn't easily visible. We can only recommend to start GnuCash on your own with your updated translation, and then check for strings which you see but are not yet translated. Those are for sure of high priority.

Two additional source code locations can be noted as low priority:

Everything from the file src/bin/gnucash-bin.c is of low priority because those are the command line options when running gnucash with different options from the command line. This is a use case that is performed only by highly experienced users which are accustomed to using the English-language command line commands. Therefore, translations here are of lower priority.
Everything from the folder src/tax or from the intl-scm/guile-string.c file with a comment indicating some file in src/reports/locale-specific is related to tax preparation in the U.S. or in Germany. Hence, those strings are uninteresting for anyone living in different countries, and you can safely consider those with very low priority.

Disambiguation prefix

At some places, GnuCash uses "disambiguation prefixes" in translatable strings. Here is an old 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.

This would be used e.g. as follows

/* Translators: This string has a disambiguation prefix */
func(Q_("Noun|Transfer"));

where the string that shows up in the GUI is simply "Transfer", but the translators need the prefix to be able to choose the correct translation of the noun vs. the verb.

In the latest gettext versions, this disambiguation is solved in yet another way by introducing an additional "context string" in addition to the translatable string, see below. As this is still a relatively new feature, we don't use this in GnuCash yet.

Context by Particular Gettext

A more recent method is "particular gettext" pgettext().

Example:

pgettext("account status: not cleared", "n")

would result in a msgid like:

#: src/app-utils/gnc-ui-util.c:656
msgctxt "account status: not cleared"
msgid "n"
msgstr ""

See Gettext Manual: Contexts for details.

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 could submit the finished translation via the GNU Translation Project. See the instructions on http://translationproject.org/ 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 Windows Installer

Follow the instructions in the this thread.

Check doc/README-*

The following filepatterns in doc/ are of interest:

README-<language>
README-<LL>.win32-bin.txt

This plain text files are often forgotten and become easily outdated. But if gnucash-doc is not installed or yelp not working, they are the only documentation, which the user can find in your language on her computer.

Q: Shouldn't it be possible by some make-magic, to adjust current-, last-stable-, next-stable- release and release-date - e.g. like target gnucash.1 in makefile? --Fell 20:21, 16 September 2010 (UTC)

How to translate the GnuCash guide and/or help files

This section describes the actions needed to translate the manuals. There are currently 2 parts:

[Concept] Guide [and Tutorial]: This introduction in the basic principles of double entry accounting and their application in GnuCash is realy useful for new users.
Help: the context sensitive help system, which is outdated and so of less use.

At least the first part consists of

text files and
pictures: png files in figures/.

At the beginning you might wish to concentrate on the text. If desired, you could link the pictures from C/figures.

The Procedure

First, you must *have* the most recent authors version of the gnucash-doc package downloaded. This is done as follows:

Checkout the documentation:
svn checkout http://svn.gnucash.org/repo/gnucash-docs/trunk gnucash-docs
Create a new directory (if it doesn't already exist) in guide/<locale> where <locale> is something like es, en_GB, or pt_PT.
Copy the files from guide/C into this directory.
Now the real work: Edit all the xml files (see below for suitable editor programs) and translate them into your language.
1. There are some general headers, which do not appear in the xml-files in your locale directory. But they can be translated by adding a section in xsl/l10n.xml. Obey the comment at the beginning. If you use non-ASCII characters, you should run recode -d <input_encoding>..h0 l10n.xml, where input_encoding might be u8 for UTF8, to get them right encoded.
2. In addition to the text, you need to recreate the image files in guide/C/figures so that they are appropriate to your language. Most of them are screenshots of a gnucash session - save them as png files because this will use a lossless compression. In theory some of the files in gnucash/doc/examples could be a starting point therefor, but they are currently - 2010-09-17 - broken.
3. Watch out: The documentation itself is probably outdated in many places, as it has been written for the 1.8.0 version of gnucash. You can watch the current progress in Concept_Guide#Ongoing_work. If you encounter any description that is wrong for the current version of gnucash, do not hesitate to ignore the english original text and instead describe the situation of the current version of gnucash in your translation. It would be even better if you have the time to change the english original text as well, but even if you can't do that, feel free to describe the actual state of gnucash in your translation and simply ignore the original english text.
  If you file a patch against the english text, you can also add your name and email address to AUTHORS, so you will become famous. ;-)
Test that your xml files have no syntax errors by running xmllint on the main file gnucash-{guide|help}.xml, e.g.:
xmllint --valid --noout gnucash-guide.xml

The program xmllint is part of the package libxml.
Optional: test your work with yelp - there are autotools files, to support you:
1. After you copied the directory, change in that directory and run once
  ./autogen.sh.
2. If you want to change some default values like installation pathes, run
  ./configure --help,
  
  to see the available options.
3. Run
  ./configure with your desired options.
4. After your editing of the files, run
  make
  
  for some additional processing.
5. If you had choosen something with "$HOME" as prefix in your configuration, run
  make install,
  
  otherwise run
  
  sudo make install.
6. Run
  yelp <path/filename>
  
  with the path, to where you installed the files.
7. Repeat steps 4-6 until everything is right.
Send your changed and added files in as .tar.gz or .zip archive to the gnucash-devel mailing list and someone there will gladly commit it into SVN. For updates a svn diff or git patch [see above] would be better than a full archive.

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

DocBook xml editors

For editing these DocBook xml files, various editors can be used; http://en.wikipedia.org/wiki/DocBook might contain pointers to some, or also http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html . People have said that AbiWord and OpenOffice have support for DocBook available, in which case you could directly edit gnucash's xml files with those.

Using po editors

Translators are more familiar with po editors like poedit,Kbabel,Gtranslator etc. In order to use po files you have first to convert xml files to po files, translate them and then convert back to xml.

First you have to install a fresh version of gnome-doc-utils. For example in a Fedora 13 system

 yum install gnome-doc-utils.

Do the convertion with the following commands (xx is your language code, example: el for Greek):
xml2po -o helpfile.xml.pot helpfile.xml

mv helpfile.xml.pot helpfile.xml.xx.po
Translate helpfile.xml.xx.po using your favorite po editor.
Convert back to xml:
xml2po -e -p helpfile.xml.xx.po -o xx_helpfile.xml helpfile.xml
Test your translated xml file as mention above:
xmllint --valid --noout xx.helpfile.xml
Remove xx from xx_helpfile.xml and you are ready to commit it in your language help directory

Workaround for the broken OpenSuse help system

As in OpenSuse 10.x and 11.x the help system is broken, there is a workaround, to review the result of your work. Locate gnucash-guide.xml in your system, probably /usr/local/share/gnome/help/gnucash/C. Then from that directory do

xmlto -o /path-to-where-you-want-to-store-docs/ html gnucash-guide.xml

which will make an html copy of the docs.

Copy over the 'figures' directory with contents to your html directory above and set a bookmark in browser to the index.html so that you get the docs any time you need them. The context sensitive facility is lost, but for general reading it works.[2]

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.

However, please take a moment to think about the intention of the account hierarchy templates. The intention of those files is much more language-related than any other of the files inside gnucash. A string-by-string translation is not the best thing to do here. Instead, you can and should find out an actual recommended account structure which makes sense in your language, and implement that one in your language. By this, I mean several of the english accounts make sense only in the U.S., but probably not in other countries. Hence, your translated account template should not contain them. Also, you can add additional parts of the account templates for your language as well, if the users are likely to need it.

For example, in the U.S., users are likely to own a car, and for this reason there is an account structure template for "Car". If in another hypothetical country users are likely to own, say, a spaceship instead of a car, you should remove the "Car" template and instead create a new account structure that represents all accounts related to the ownership of a spaceship, and offer this as additional "Spaceship" template.

In other words, you should feel free to create a completely new account template structure that is most suited to your language. The english-language templates are just a proposal, but will need further adaption and not a string-by-string translation.

Having said that, here is how you would start for a direct translation of the English templates:

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

For each file:

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.
For each gnc:account in the file translate the act:name, and act:description fields. Please do not translate any other fields.

Note again: 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.

If you need some additional guids, this funny random numbers, you can use:

gnucash-make-guids

or, if that command does not exist,

uuidgen | sed -e 's/-//g'

AccountHierarchyTemplate describes, how to create new templates e.g. for business purpose according local rules.

How to translate the website

Get a checkout of http://svn.gnucash.org/repo/htdocs/trunk
Run the command
```
make pot
```
Then depending on whether or not a translation for you language exists already (complete or not):
1. Existing translation:
  Run the command
```
msgmerge po/LL.po po/gnucash-htdocs.pot -o po/LL.po
```
  Where LL is your language code, see earlier sections
2. New translation:
  Copy the newly created file po/gnucash-htdocs.pot to po/LL.po, where LL is your language code, see earlier sections
Translate the po file as usual
Optionally run
```
recode -d <input_encoding>..h0 po/LL.po
```
to get special characters HTML quoted.
Send the LL.po to gnucash-devel; the maintainers will commit this to SVN and add the appropriate Makefile rules upon the first SVN commit.

Note: these instructions are written for linux. They will probably work on other unix-like systems as well, but not on Windows. On Windows you may be able to do this if you set up a linux-like environment (with cygwin or mingw), but that's untested so far.

Tips for Developers

How to make strings in code translatable

This section collects some notes for developers/programmers on how to correctly prepare their code for translations.

Strings in Glade files are marked for translations by the (_ ) functions.

Normally, strings in C code just need to be enclosed with the _( ) function (well, actually it is a macro expanding into a function, but this is usually just an implementation detail). For example,

func("A translatable string!");

should instead be written as

func(_("A translatable string!"));

However, it is important to keep in mind that _( ) is a function; this means that in certain situations it cannot be used. For example,

gchar* array_of_strings[] = {_("first string"), _("second string"), _("third string")};

would cause a compiler error. Instead, these strings should be wrapped with the N_( ) macro, which is declared as #define N_(String) gettext_noop(String). Then, whenever one of the strings is actually used (as opposed to declared), it should be wrapped with the _( ) function again:

gchar* array_of_strings[] = {N_("first string"), N_("second string"), N_("third string")};
func(_(array_of_strings[0]));

How to give the translators a clue

Sometimes it is useful to give the translators some additional information about the meaning of a string. To achieve this effect, you can insert a section of comment lines direct before the related string, where the first comment starts with "Translators:". There must not be any control statement between comment and string.