Difference between revisions of "Translation"

From GnuCash
Jump to: navigation, search
(DocBook xml editors: add Eclipse)
(The Procedure: Update for cmake)
(422 intermediate revisions by 9 users not shown)
Line 1: Line 1:
HOWTO: Translating GnuCash<br>
+
;Tip: Use [https://translate.google.com/translate?hl=en&sl=en&tl=de&u=https%3A%2F%2Fwiki.gnucash.org%2Fwiki%2FTranslation&sandbox=1 Google translation] and select your language to get a translation of this document.
 +
The concept of this document is to give you step-by-step instructions on how to create or update ''translation''s and other ''localization'' tasks for the gnucash project.  See [[Translation Status]] for the current status of the project with respect to translation contributions.
  
The concept of this document is to give you step-by-step instructions on
+
== Overview ==
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.
 
  
== Mailing lists, IRC and web sites ==
+
GnuCash has several separate areas that need translations or localization, which are by priority:
 +
* A [[#The glossary file|glossary file]]: A reference in form of a ''message catalog'' with roughly '''200''' terms that are commonly used throughout GnuCash and their '''explanation'''. Preferably it should be translated first for each new language to define a consistent terminology for the other parts.
 +
* The [[#Translating the Program|program]]'s '''message catalogs''': These contain all text messages for the application's user interface. It currently consists of roughly '''5000''' strings. Not all are equally important though.
 +
: The following languages are currently maintained at the [[#translationproject.org]]: [https://github.com/Gnucash/gnucash/blob/maint/po/CMakeLists.txt#L4-L5]
 +
* A [[#How to translate the Windows Installer|Windows Installer]] with about '''20''' strings.
 +
* The [[#How to translate the files containing the new account hierarchies|account templates]]: A set of ready to use account chart snippets ''for personal users'' that can be mixed and matched into a full chart of accounts during the creation of a new a new GnuCash file with currently '''115''' translatable account names.
 +
:*If your government or other authorities offer specific templates ''for business users'', you can create them, too.
 +
* The [[#Translating the GnuCash Guide and Help|documentation]]: The Help Manual and the [[Concept Guide|Tutorial and Concepts Guide]]. These documents explain how to use GnuCash. They are written in DocBook, an XML variant.
 +
* The [[#How to translate the website|website]], while mostly written in PHP/HTML, uses ''message catalogs'', too. Currently it has '''430''' messages.
 +
** In theory one could also translate recent announcements from the '''news''' directory into the language specific subfolder, but ususally there are more important tasks around.
 +
* [[#How to create localized Income Tax Tables|Income Tax Tables]] require some knowledge of your regional tax rules and are related to ''account templates''.
 +
* Optionally you can [[#Check Files in Repo gnucash's doc Directory]] files, too.
 +
GnuCash uses the translation of the ISO 4217 '''currency''' codes and names. This are maintained by the [https://salsa.debian.org/iso-codes-team/iso-codes ISO Codes Team]. If your language is missing or has issues contact them.
  
=== GnuCash ===
+
== Available resources ==
Translators will probably find two gnucash mailing lists of interest.
+
There are many resources to support you at gnucash.org and other places. Don't hesitate to use them.
 +
 
 +
=== gnucash.org ===
 +
We have collected a bunch of useful information for you here in this wiki -
 +
:navigate from the [[GnuCash|main page]] or use the search function -
 +
and on the website {{WebURL}}.
 +
 
 +
And we have several channels of communication and a few other useful tools:
 +
 
 +
==== IRC ====
 +
The fastest way to get help is using the '''internet relay chat''' [[IRC]], as many of the developers hang out there and are eager to help.
 +
 
 +
==== Mailing lists ====
 +
Translators will probably find two or three gnucash mailing lists of interest. If you can not find the answers to your questions in their [[Mailing_Lists#Mailing List Archives]], feel free to ask them.
 +
* For ''language and region specific questions'', where you should discuss terms and ask for proofreading of your work, use your languages mailing list. Currently we have
 +
*: '''gnucash-'''[pt_]'''br''',''' de''',''' es''',''' fr''',''' it''',''' nl'''.
 +
: If none exists for your language or nobody has an answer there, use the english lists:
 
* ''General use questions'' and answers are found on the '''gnucash-users''' mailing list,
 
* ''General use questions'' and answers are found on the '''gnucash-users''' mailing list,
* specific ''development questions'' go to the '''gnucash-devel''' list and
+
* specific ''development questions'' go to the '''gnucash-devel''' list.
* your finished translation file are also sent to the ''gnucash-devel'' list.
+
* If you dislike the heavy traffic on the above lists, you should at least subscribe the [{{ListURL}}/mailman/listinfo/gnucash-announce gnucash-announce] list to get informed about new releases.
  
To ''subscribe'' or ''view archives'' of these lists follow the links to the [[Mailing Lists]]:
+
To ''subscribe'' or ''view archives'' of these lists follow the links to the [[Mailing Lists]].
http://wiki.gnucash.org/wiki/Mailing_Lists
 
  
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.
+
=== translationproject.org ===
 +
The [{{URL:TP}} Translation Project] coordinates the ''message cataloges'' of several ''programs''; you can see which ''languages'' they host on their [{{URL:TP}}domain/gnucash.html GnuCash page] and learn about their process [{{URL:TP}}html/translators.html here].
  
The main gnucash '''web site''' is loaded with information:
+
If you want to help with an existing Translation Project translation or add a new translation under their aegis, please contact the ''language team'' using the information on their [{{URL:TP}}team/ team page].
http://www.gnucash.org/
 
  
=== GNU Translation Project ===
+
==== Coordinating Message Catalog Translations ====
The GNU Translation Project is another way to submit translations:
+
===== New Message Catalogs =====
http://translationproject.org/
+
The Translation Project requires that you use either an existing translation or <tt>gnucash.pot</tt> from the latest release as the basis for your translation.
  
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
+
===== Updating Message Catalogs =====
* (a) send it to the [[Mailing Lists|Mailing List]] gnucash-devel, or
+
Usually you will use your po file from their site, but sometimes we apply global changes like removing the trailing colon from GUI labels. In that case you can save time by merging such updates from [https://github.com/Gnucash/gnucash/tree/maint/po our version].
* (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 [[Subversion|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.
+
==== Coordinating Account Templates and Documentation ====
 +
The Translation Project handles only message catalogs, so if you have ''glossaries'', ''account templates'' or ''documentation translations'' you'll submit them  [[#Direct Contribution|directly to us]].
  
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.
+
=== Direct Contribution ===
 +
If you want to work on a translation that's not coordinated by the Translation Project or a new translation and you want to submit it directly to GnuCash, read on. If it's an existing translation please try to contact the last translator first using the contact information in the message catalog.
  
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,
+
If you're starting a new translation it's much easier to begin with a tarball, which will include <tt>po/gnucash.pot</tt>; if you start from a [[Git]] clone you'll have to [[Building|build]] Gnucash yourself first to generate <tt>gnucash.pot</tt>.
only at release time. [https://lists.gnucash.org/pipermail/gnucash-devel/2010-July/028990.html]
 
  
:(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.)
+
=== On Other Sites ===
 +
==== General Translations Guidelines and Tips ====
 +
General information about how to approach the translation of software can be found here:
 +
* TranslationProject
 +
** {{URL:TP}}html/translators.html
 +
** {{URL:TP}}html/software.html
 +
* Gnome
 +
** Human Interface Guide https://developer.gnome.org/hig/stable/
 +
** GNOME Documentation Style Guide https://developer.gnome.org/gdp-style-guide/
 +
** {{URL:GTP}}
 +
** {{URL:GTP}}/LocalisationGuide
 +
* KDE
 +
** [https://l10n.kde.org/docs/translation-howto/index.html The KDE Translation HOWTO]
  
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.
+
==== Other Web Based Translation Tools ====
 +
Several services for translation coordination exist, see [[Improve Localization Process#Web Based Translation Tools]]. As we have no experience with them contact the gnucash-devel mailing list before using them.
  
=== General Translations ===
+
===== Weblate  =====
General information about how to approach the translation of software can be found here:
+
Since 2020-12-14 we are experimenting on [https://hosted.weblate.org/projects/gnucash/ GnuCash @ Hosted Weblate].
* http://l10n.kde.org/docs/translation-howto/index.html
+
*We appreciate any help on the optimal configuration by '''experienced weblate users'''. You can contact the GnuCash team by {{IRC-URL}} or [[Mailing Lists]].
* http://developer.gnome.org/projects/gtp/l10n-guide/
+
*If you already have been a '''GnuCash translator''', tell us on {{IRC-URL}} ([[IRC|help about IRC]]) your Weblate name to become a weblate/GnuCash reviewer there.
* http://developer.gnome.org/projects/gtp/resources.html
 
  
=== Other Useful Sites ===
+
==== Other Useful Sites ====
 
* There are many online dictionaries, use a search engine like google, to find the best fitting.
 
* There are many online dictionaries, use a search engine like google, to find the best fitting.
 +
* An index of on-line dictionaries and a lot of other resources can be found at www.yourdictionary.com.
 
* Comparing articles on wikipedia in your language and english can be helpful.
 
* Comparing articles on wikipedia in your language and english can be helpful.
* In special cases the terminology database of the European Union [http://iate.europa.eu/iatediff/SearchByQueryEdit.do Inter Active Terminology for Europe] can be used, too.
+
* In special cases the terminology database of the European Union [https://iate.europa.eu/info/documentation Inter Active Terminology for Europe] can be used, too.
 +
 
 +
== How to submit changes directly to GnuCash ==
 +
Once you've got a translation ready for submission, there are three options:
 +
 
 +
=== Pull Requests at GitHub ===
 +
If you already are a github user you can publish your work as a separate branch on your gnucash[-{[ht]docs|on-windows}] fork and send a pull request to the GnuCash team. If you wish to continue your work before the request was completed, simlply create a new working branch. After the pull request was completed you can delete the related branch again. See [[Git]] for details.
 +
;Commit messages: Start your commit message with <tt>L10N:<LL>: </tt> were <LL> - or ${LL} below - is your language code.
 +
:If applicable, add a with the output of <Syntaxhighlight lang="sh" inline>msgfmt -c --statistics ${LL}.po</Syntaxhighlight>.
 +
:Also the <tt>POT-Creation-Date</tt> might be of interest to see how recent the translation is.
 +
:;Example: <tt>L10N:de: 5423 übersetzte Meldungen.</tt>
 +
 
 +
=== Patches at Bugzilla ===
 +
The easiest is to use [[Bugzilla]]:
 +
* [{{BugURL}}/createaccount.cgi Create an account] if you still have none or [{{BugURL}}/index.cgi?GoAheadAndLogIn=1 login],
 +
* [{{BugURL}}/enter_bug.cgi?product=GnuCash&component=Translations&bug_severity=enhancement create an ''request for enhancement'' bug against the Gnucash ''component translations''], choose the version on which your patch is based and
 +
* attach a patch
 +
:containing the diff between the old files - if any - and your new files:
 +
:* If you have [[Git]] installed, the easiest way to create the patch is <code>git format-patch origin/maint..maint</code>.
 +
:* Else you can use ''diffutils'': <code>diff -u[r] <original path> <modified path> > <name>.patch</code>. See <code>info diff</code> for details.
 +
 
 +
=== Mailing lists ===
 +
You can simply email your completed message catalog (<tt>.po</tt> file) to the developers at the [mailto:gnucash-devel@gnucash.org gnucash-devel] mailing list. We'd really rather you use Bugzilla or Github because those are much less likely to get lost or forgotten, but if you really find those too hard we'll try to accommodate you on the list.
  
== Get the source from SVN ==
+
== Translating the Program ==
 +
To begin a translation you need either the message template file (gnucash.pot) if you're starting a new translation or the existing message catalog (xx.po or xx_YY.po, where xx is the ISO code for your language and YY the ISO code for a language-variant locale, see [[#Naming Convention|Naming Convention]]). These files are in the gnucash sources, which you can obtain either from our [https://github.com/Gnucash/gnucash.git git repository] or by downloading the latest '''release''' tarball from [https://www.sourceforge.net/projects/gnucash/files/gnucash%020(stable) Sourceforge].
  
GnuCash uses [[Subversion]] as a repository server. [[Subversion|Click here]] for an introduction to subversion. Alternatively you can also use [[Git]]; look [[Git|there]] for the equivalent commands.
+
=== Get the source from Git ===
 +
GnuCash uses [[Git]] as a version control system. [[Git|Click here]] for an introduction to Git.
  
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.
+
The first thing to do is ''usually'', to download the latest STABLE branch, called '''maint''', of gnucash from git and get it to compile.  '''See [[Translation Status]] to choose which branch to use for translations'''.  Do not use the ''master'' branch ''unless specifically mentioned in [[Translation Status]]''.  Because the text in the ''master'' branch changes so much it would be a waste of time to translate  it.  Do not worry, when the ''master'' branch becomes stable the existing  translations in the STABLE branch will be merged.  Your work will not be lost.
  
Checkout the current stable branch.
+
Normally checkout the current stable branch:
svn checkout <nowiki>http://svn.gnucash.org/repo/gnucash/branches/2.4</nowiki> gnucash-2.4
+
<Syntaxhighlight lang="sh">
 +
git clone https://github.com/Gnucash/gnucash ${SOURCEDIR}
 +
cd ${SOURCEDIR}
 +
git checkout maint
 +
</Syntaxhighlight>
  
The argument "gnucash-2.4" above can be whatever you want your local directory to be called,
+
The argument '''${SOURCEDIR}''' 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.4" created
+
and is optional in the first line. If you leave it out, you'll have a directory called <tt>gnucash</tt> created
containing all the source code.
+
containing all the source code ''below your current working dir''.
  
Checkout the documentation (optional, but recommended)
+
Checkout the documentation (optional, but recommended):
svn checkout <nowiki>http://svn.gnucash.org/repo/gnucash-docs/trunk</nowiki> gnucash-docs
+
<Syntaxhighlight lang="sh">
 +
git clone https://github.com/Gnucash/gnucash-docs gnucash-docs
 +
cd gnucash-docs
 +
git checkout maint
 +
</Syntaxhighlight>
  
After this initial SVN checkout, you can later update your SVN files using:
+
==== Update your repository ====
svn update
+
After this initial git checkout, you can later update your local repository using
 +
<Syntaxhighlight lang="sh">
 +
git pull --rebase
 +
</Syntaxhighlight>
 +
from anywhere in the tree of ${SOURCEDIR}. We recommend to do it daily when you start your work.
  
== Compile & Install ==
+
=== Get packages, which are used while building  ===
 +
* [[Dependencies]] contains the list of packages, which are used while building GnuCash. If some are missing the configuration by <tt>cmake</tt> or the build by <tt>make</tt> or <tt>ninja</tt> will fail.
 +
* For working on .po files we use several commands starting with <tt>msg</tt>. This are part of '''gettext-tools'''.
 +
:;Caution: Gettext versions < 0.20 are known not to extract the 'developer_name' xml node, which contains the msgid "GnuCash Project". Do not remove this msgid!
 +
Under Linux use your package manager and install them.
  
Before starting to work on your translations, it is suggested that you  
+
=== Steps in the Build System ===
compile the gnucash source code. This way you can get your system set up
+
GnuCash uses the [https://cmake.org cmake] build generator to control the build of all components. Details are described in [[Building]]. The following short-form instructions work on Unix systems and assume that you have already set up the dependencies according to [[FAQ#Q:_I_heard_it_is_too_hard_to_compile_GnuCash.21|the FAQ]]. If you are building the unstable or master branches you'll need to use your package manager to install two more development packages, boost-all-devel and googletest.
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 ===
+
==== Configuration ====
 +
It's generally preferred to use a separate build directory. For translators it's convenient to make this a hidden directory in the source directory as that provides the least complicated paths in the translation template; hiding the directory prevents the extraction tool from including build products in the files searched for translatable strings. We'll call the directory <code>.build</code>. You can call it anything you like, just remember to start the name with a dot so that it's hidden.
  
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.
+
Change directories to your ''build directory'' and run cmake to configure the build. In most cases translators will not need to install GnuCash and it will build any arguments: <Syntaxhighlight lang="sh">
 +
cd ${BUILDDIR} # e.g. .build
 +
cmake ..
 +
</Syntaxhighlight>
 +
tells cmake to configure the current directory using the CMakeLists.txt in the parent directory. If configuration fails or if you want to refine your build consult [[Building]].
 +
 
 +
==== Optional Compile ====
 +
It is suggested that you compile the gnucash source code. 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.  
  
Note: there are some warnings that spew forth during autogen. Do not worry about them, apparently they are normal and can be ignored.
+
===== make =====
 +
;Note: Advanced users might consider to use [[Build_Tools#Ninja|Ninja]] instead of [[Build_Tools#Make|Make]], but that is behind the scope of this page.
 +
Next, compile gnucash in the ''build directory'':
 +
<Syntaxhighlight lang="sh">
 +
cd ${BUILDDIR} # e.g. .build
 +
make
 +
</Syntaxhighlight>
  
=== configure ===
+
GnuCash can be run from the ''build directory'' as follows:
 +
<Syntaxhighlight lang="sh">
 +
cd ${BUILDDIR} # e.g. .build
 +
GNC_UNINSTALLED=1 GNC_BUILDDIR=`pwd` bin/gnucash
 +
</Syntaxhighlight>
 +
 
 +
It is a good idea to use absolute paths like this to insure you run
 +
the proper gnucash executable.  To run your distributions pre-installed version of
 +
gnucash, under Linux usually you can type:
 +
<Syntaxhighlight lang="sh">
 +
/usr/bin/gnucash
 +
</Syntaxhighlight>
 +
<!--FIXME: Other OSes-->
 +
 
 +
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. You can find details in [[Locale Settings]].
  
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.
+
==== Documentation ====
 +
The ''GnuCash Help Manual'' and the ''Tutorial and Concepts Guide'' can either use the same [[CMake]] build system as the code or the older [[Build_Tools#Autotools|Autotools]].
  
cd gnucash
+
* To make a browsable documentation set with Autotools:
./autogen.sh
+
*# <code>git clone gnucash-docs</code> or unpack a gnucash-docs tarball
./configure --enable-debug --prefix=/opt/gnucash-svn
+
*# create a hidden build directory just as you did for GnuCash itself
 +
*# run autogen.sh <Syntaxhighlight lang="sh">
 +
./autogen.sh
 +
</Syntaxhighlight>
 +
*# change directory into the build directory <Syntaxhighlight lang="sh">
 +
cd .build
 +
</Syntaxhighlight>
 +
*# run the following commands <Syntaxhighlight lang="sh">
 +
../configure
 +
make html
 +
</Syntaxhighlight>
  
If configure complains about missing development packages, find them on your favorite OS/distribution, install it, and try to re-run the configure command.
+
* To make a browsable documentation set with CMake:
See your local copy of the [http://svn.gnucash.org/trac/file/gnucash/trunk/README.dependencies README.dependencies] file for library dependency notes.
+
*# <code>git clone gnucash-docs</code> or unpack a gnucash-docs tarball
Also check out [[Dependencies|the dependencies page]].
+
*# create a hidden build directory just as you did for GnuCash itself
Eventually, you should be able to get autogen to run without any error
+
*# change directory into the build directory <Syntaxhighlight lang="sh">
messages.
+
cd .build
 +
</Syntaxhighlight>
 +
*# run the following commands <Syntaxhighlight lang="sh">
 +
cmake ..
 +
make html
 +
</Syntaxhighlight>
  
=== make ===
+
The new documentation home pages will be
 +
:<code>guide/<locale>/gnucash-guide/index.html</code> and
 +
:<code>help/<locale>/gnucash-help/help.html</code>,
 +
where <locale> is one of <code>C, de, it, ja, or pt</code> (English, German, Italian, Japanese, or Portuguese respectively). You can use the <code>file:</code> URL scheme to point your browser to one of them; the links will work from there.
  
Next, compile gnucash:
+
=== Naming Convention ===
 +
The language code is of the following form:
 +
:;<language>[_<REGION>][.<Charset>][@modifier]:using the well known ISO codes [{{URL:wp}}List_of_ISO_639-1_codes 639-1] for '''language'''s and [{{URL:wp}}ISO_3166-1 3166-1] for '''region'''s, which are in most cases countries .
 +
:* Only ''if no 2 letter code exists'' for your language in ISO_639-1, use the 3 letter code from [{{URL:wp}}List_of_ISO_639-2_codes ISO_639-2].
 +
* If you are the first translator for your language, you should
 +
** name your files and directories ''only with your language code''.
 +
** set <tt>Language:</tt> in the header of your po file with the full (language and region) code, if significant.
 +
: So all people using your language despite of their region will benefit from your work.
 +
* If there are parts, which are ''specific for your region'', e.g. business account templates respecting local law, then they should be in a <language>_<REGION> directory.
 +
* The common '''charset''' in gnucash is [{{URL:wp}}Utf8 utf8].
 +
* In the rare case ''different scripts'' are used for the same language like kyrilic and latin add for the less used the '''modifier''' e.g. <tt>sr@latin</tt>.
  
make
+
In the following parts of this document 'XXXX' and 'LL' refer to your language code.
  
=== make install ===
+
=== Contact the maintainer of your language ===
  
To install (assuming "make" completed without any problems) you must be
+
To find out who is the last person to work on your language, look near the
root.
+
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.
  
su -  
+
The beginning of your .po file should look something similar to this:
make install
+
<syntaxhighlight lang="po" highlight="13">
 +
# 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"
 +
"Report-Msgid-Bugs-To: https://bugs.gnucash.org/enter_bug.cgi?"
 +
"product=GnuCash&component=Translations\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"
 +
"Language: pt_BR\n"
 +
"MIME-Version: 1.0\n"
 +
"Content-Type: text/plain; charset=UTF-8\n"
 +
"Content-Transfer-Encoding: 8bit\n"
 +
"Plural-Forms: nplurals=2; plural=n != 1;\n"
 +
</syntaxhighlight>
  
To compile the documentation, enter the gnucash-doc directory and go
+
Look to see who the "Last-translator" was, and send an email to that person
through the same process:
+
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 or does not answer in reasonable time), you will become
 +
the maintainer and you should change the "Last-Translator" to your name and
 +
email address.
  
./autogen.sh
+
=== The glossary file ===
  ./configure --prefix=/opt/gnucash-svn
+
Inside the po/glossary/ directory should be a "glossary" file for your
make
+
languageThis file contains a bunch of ''commonly used terms'' found in GnuCash - and the explanation of a few very specific for GnuCash like the disambiguation between ''bill'', ''invoice'' and ''voucher''.
  su -
+
It is recommended that you '''get this file translated first''', and use it as a
make install
+
guide when translating the real .po file or the documentation. Please keep in mind that this file will ''never be visible to a user''! The glossary file is only a tool for you, the translators! I repeat: The strings from the glossary file will ''never'' be user-visible, they are only used by you, the translator.
  
== Running GnuCash==
+
::;Todo: The current files have a very informal form. To make them more useful like conversion in tool specific glossary formats, we should replace <syntaxhighlight lang="po">
 +
msgid "generic term: term"
 +
</syntaxhighlight> by <syntaxhighlight lang="po">
 +
msgctxt "generic term"
 +
msgid "term"
 +
</syntaxhighlight>
  
After installation, insure that it works by running (as a normal user,
+
# Go into the glossary directory: <Syntaxhighlight lang="sh">
no need to be root here):
+
cd po/glossary/
 +
</Syntaxhighlight>
 +
# If your .po glossary file ''does not exist'' or ''is older than'' <tt>gnc-glossary.txt</tt>, create the template: <Syntaxhighlight lang="sh">
 +
./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot
 +
</Syntaxhighlight>
 +
# Create or update your language's glossary file:
 +
#* If your .po glossary file ''does not exist'',  
 +
## use this gnc-glossary.pot file to create it with <Syntaxhighlight lang="sh">
 +
msginit # add -l<locale> if different from your settings
 +
</Syntaxhighlight>
 +
## Add your file into the <tt>set_dist_list(po_glossary_DIST ...)</tt> command in <tt>glossary/CMakeLists.txt</tt> <Syntaxhighlight lang="sh">
 +
set_dist_list(po_glossary_DIST CMakeLists.txt bg.po ca.po da.po de.po el.po es_NI-policy.txt es.po fr.po gnc-glossary.txt he.po
 +
        hr.po hu.po it.po nb.po nl.po pl.po pt_BR.po pt.po ru.po rw.po sk.po sv.po txt-to-pot.sh vi.po zh_CN.po zh_TW.po)
 +
</Syntaxhighlight> to get it in the tarball.
 +
## After changing CMakeLists.txt you have to rerun <Syntaxhighlight lang="sh">
 +
cmake # add your options
 +
</Syntaxhighlight>
 +
#* If your .po glossary file ''exists'', but is older than <tt>gnc-glossary.txt</tt> use the msgmerge program to update it: <Syntaxhighlight lang="sh">
 +
msgmerge --previous -U LL.po gnc-glossary.pot;
 +
</Syntaxhighlight>
 +
# Now open your language's glossary file and translate it completely.
 +
# Don't forget to [[#Check syntax and statistics of your .po file]].
  
/opt/gnucash-svn/bin/gnucash
+
==== Terms missing or inadequate in the glossary file ====
 +
If you detect an important term which is missing or could be better explained,
 +
* create a pull request at github or
 +
* [[Bugzilla#Using_Bugzilla|open a bug]] for Product:GnuCash, Component:Translation and add a [[Git#Patches|patch]]
 +
: for the ''source file'' '''gnc-glossary.txt'''.
 +
With the exception of the header the lines of this file are alphabetical sorted and have the form: <Syntaxhighlight lang="text">
 +
Msgid<TAB>Comment
 +
</Syntaxhighlight>
 +
:;Reminder: Does your editor enter <TAB>s or will it replace them with <Space>s?
 +
To test it, run the following steps after you changed gnc-glossary.txt:
 +
# To generate a new gnc-glossary.pot: <Syntaxhighlight lang="sh">
 +
./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot</Syntaxhighlight>
 +
# run above ''msgmerge'' command for your LL.po,
 +
# check and translate the new string in this updated glossary file.
 +
# If successful, update all *.po files with: <Syntaxhighlight lang="sh">
 +
for i in *.po; do echo -n "$i:"; LANG=C msgmerge --previous -U $i gnc-glossary.pot ; done
 +
#old form: find *.po -exec /usr/bin/msgmerge --previous -U '{}' gnc-glossary.pot \;
 +
</Syntaxhighlight>
 +
;Note: The last step can also be done by a maintainer.
 +
:<tt>LANG=C</tt> is only recommend for maintainers to get english error messages.
  
It is a good idea to use absolute paths like this to insure you run
+
=== Get a fresh template ===
the proper gnucash executable. To run your OS pre-installed version of
+
The ''Portable Object Template'' (.pot file) is a collection of all translatable strings.
gnucash, usually you can type:
 
  
/usr/bin/gnucash
+
It is important, to repeat this step e.g. after you asked a developer to change an insufficient string or you got an announcement about changed strings like commit messages starting with "<tt>I18N: </tt>" or containing a "<tt>[I18N]</tt>" flag.
  
In either case, you can easily switch between the various languages the
+
:;Tip: If you have problems with this section, you download instead the "current template" from [https://translationproject.org/domain/gnucash.html the translationproject.org]. But keep in mind it is based on the last release and does not contain recent changes.
gnucash has available by placing the LANG env var before the call to the
 
executable. You can find details in [[Locale Settings]].
 
  
== Naming Convention ==
+
# If your repository is no fresh checkout, you should first [[#Update your repository]]: <Syntaxhighlight lang="sh">
 +
git pull --rebase
 +
</Syntaxhighlight>
 +
# Only on the first run see [[Building]] to set up your build environment depending on your OS.
 +
#;Note: As you can use <tt>make</tt> or <tt>ninja</tt>, on this page we write always <tt>make <target></tt>. If you decided to use ninja, execute <tt>ninja <target></tt> instead.
 +
# Then in gnucash, a specific command ''at the '''top-level''' of the build tree'' (or source tree, if you do not use a separate build directory) will perform all necessary steps for this: <Syntaxhighlight lang="sh">
 +
cd ${BUILDDIR} # adjust ${BUILDDIR}
 +
make pot
 +
</Syntaxhighlight>
 +
# If make complains <Syntaxhighlight lang="console" inline>make: *** No rule to make target `<path/to/missing-source-file>', needed by `gnucash.pot'.  Stop.
 +
</Syntaxhighlight> there are obsolete relicts from a previous build. Just run <Syntaxhighlight lang="sh">
 +
make clean  # remove obsolete files
 +
make pot    # try it again
 +
</Syntaxhighlight>
 +
# Now go into the po directory: <Syntaxhighlight lang="sh">
 +
cd ${SOURCEDIR}/po # adjust ${SOURCEDIR}
 +
</Syntaxhighlight>
 +
If your language file ''already exists'', continue with [[#Update an existing .po file]].
  
The language code is of the following form:
+
=== Build a new .po file ===
:<language>[_<COUNTRY>[.<Charset>]]
 
using the well known ISO codes [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes 639-1] for languages and [http://en.wikipedia.org/wiki/ISO_3166-1 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 is no .po file for your language, then you can start a new one. Start by
 +
<SyntaxHighlight lang="sh">
 +
msginit [-lLL[_RR]] [-i<path/to/>gnucash.pot]
 +
</SyntaxHighlight>
 +
where <tt>LL</tt> is your language and <tt>RR</tt> your region code, if there is already a different LL.po like e.g. ''pt'' and ''pt_BR''.  
 +
: -i<path/to/>gnucash.pot is required, if you use a separate build dir,
 +
: -l... is only required, if your target is different from your environments current language.
 +
This will initialize the meta information with values from your user environment.
 +
;Note: msginit  0.19.3 is querying an obsolete address of the translation project for language teams, but that doesn't matter.
  
If there are parts, which are s''pecific for your country'', e.g. business account templates respecting local law, then they should be in a <language>_<COUNTRY> directory.
+
If that does not work you can copy the file <tt>gnucash.pot</tt> into a work file named <tt>LL.po</tt> and just edit this file.
  
The common '''charset''' in gnucash is [http://en.wikipedia.org/wiki/Utf8 utf8], but there might be issues in MS Windows specific parts. [FIXME: Still existent?]
+
==== Adjust the header and special messages ====
 +
The top of the .po file should be edited somewhat. Most of this adjustments should already be done by <tt>msginit</tt>, but if you copied the template, you will have to adjust all.
  
In the following parts of this document 'XXXX' and 'LL' refer to your language code.
+
* The comments at the top of the file should be changed to be current: <SyntaxHighlight lang="po">
 +
# Messages in Deutsch fuer GnuCash
 +
# Copyright (C) 1999 Free Software Foundation, Inc.
 +
# Jan-Uwe Finck <Jan-Uwe.Finck@bigfoot.de>, 1999.
 +
</SyntaxHighlight>
 +
:Expand the copyright comment by a list of <code><Translator name> <email address>, year[ range]</code> in ''reverse'' historical order. Then you can later copy the list into <tt>translator-credits</tt>.
 +
:* This is also a good place to record ''typographic conventions'', if more than one person work on the file: <SyntaxHighlight lang="po">
 +
#
 +
# Konventionen/Tastenkürzel:
 +
# »Zitate«: [altgr]+[Y]/[X]
 +
# Gedankenstrich — [altgr]+[Shift]+[-]
 +
</SyntaxHighlight>
  
== The glossary file ==
+
* The first, empty msgid "" contains information for you and the gettext tools. Each line of the msgstr contains a '''capitalized entry''', a colon and a value. ''Replace all uppercase words'' with something appropriate. In this case, you will be the first author of the translation, and also the
 +
:* <tt>Last-Translator</tt>: ''your name'' and ''email address''. This person is responsible for the file, so we need an email address to contact you.
 +
::Do not change it, if you do not want to become the responsible person. Despite that you can add yourself to the above copyright section and <tt>translator-credits</tt> below.
 +
:* <tt>Language-Team</tt>: Some languages are maintained by teams and everybody wants to get informed. That is the case for organizations like [[#translationproject.org]] or the german Gnucash translator team. Enter the  teams name and email address. If you are no member of a team, keep it empty or write <tt>NONE</tt>. Team members can reuse this line in <tt>translator-credits </tt>
 +
:* <tt>Language</tt>: should be the same as the filename without extension, usually the ISO code of your language.
 +
:* <tt>Project-Id-Version</tt>: <Package name> and <Version>. Do not forget to update the version. <tt>msgmerge</tt> seems not to be able to do it for you.
 +
:* <tt>Report-Msgid-Bugs-To</tt>: Should already been set by .<tt>msginit</tt> to <tt>{{BugURL}}/buglist.cgi?roduct=GnuCash&component=Translations</tt> or similar, where you can report issues with the <tt>msgids</tt> like
 +
:** "There is a typo in <msgid>" or
 +
:** "<msgid> is impossible to translate to <your language> because of the grammatical difference …"
 +
:* <tt>POT-Creation-Date:</tt> gets updated by <tt>msgmerge</tt>.
 +
:* <tt>PO-Revision-Date</tt>: The timestamp of the last modification. Editors with a specific po mode should update it on saving. If you use a normal text editor, you will have to do it manually.
 +
:* Do not change the content section: <syntaxhighlight lang="po">
 +
"MIME-Version: 1.0\n"
 +
"Content-Type: text/plain; charset=UTF-8\n"
 +
"Content-Transfer-Encoding: 8bit\n"
 +
</syntaxhighlight> Older files can have an older form like: <syntaxhighlight lang="po">
 +
"CHARSET: UTF-8\n"
 +
"ENCODING: 8bit\n"
 +
</syntaxhighlight>. Replcae them with the recent form.
 +
:* Make sure that the header of your .po file contains an adjusted form, e.g. for slavian languages set nplurals=3, of this line: <SyntaxHighlight lang="po">
 +
"Plural-Forms: nplurals=2; plural=n != 1;\n"
 +
</SyntaxHighlight>
 +
::See [https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/Translating-plural-forms.html#Translating-plural-forms Gettext Manual: Translating Plural Forms] for details.
 +
:See the full explanation in [https://www.gnu.org/software/gettext/manual/html_node/Header-Entry.html Gettext Manual: Header Entry].
 +
:* Remove the `#, fuzzy' line once you have specified the items in capitals, because once this is done the header entry is no longer fuzzy.
  
Inside the po/glossary/ directory should be a "glossary" file for your
+
* There is currently one '''special string''': <SyntaxHighlight lang="po">
language.  This file contains a bunch of commonly used terms found in gnucash.
+
#: ../src/gnome-utils/gnc-main-window.c:4389
It is recommended that you get this file translated first, and use it as a
+
msgid "translator-credits"
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.
+
msgstr ""
 +
"Joachim Wetzig, 2019\n"
 +
:
 +
"Jan-Uwe Finck, 1999\n"
 +
"\n"
 +
"Verbesserungsvorschläge zur Übersetzung an gnucash-de@gnucash.org"
  
Go into the glossary directory and rebuild your language's glossary file:
+
</SyntaxHighlight>
 +
:This will appear in <tt>Help->About->Credits->Translation</tt>. So you should enter your ''name'' or that of your team and an ''email'' address where users can contact you for typos and gifts.
 +
:;Tip: After some time more persons would have worked on the translation. Then you can expand it from your header comments to: <SyntaxHighlight lang="po">
 +
msgstr ""
 +
"<current translator>, <years>\n"
 +
"<previous translator>, <years>\n"
 +
:
 +
"<first translator>, <years>\n"
 +
"\n"
 +
"Send suggestions, critizism and questions about this translation to\n"
 +
"Klingon speaking GnuCash community <gnucash-tlh@gnucash.org>\n."
 +
"To avoid moderation we recommend to subscribe at\n"
 +
"<a
 +
# This comment exists only to trick the spamfilter. Rejoin the surrounding lines again.
 +
href=\"{{ListURL}}/mailman/listinfo/gnucash-tlh\">List gnucash-tlh</a>"
 +
# Don't forget to replace Klingon (tlh) by your language and translate the rest!
 +
</SyntaxHighlight> If a list exists, we suggest to remove the email address of individuals for data protection reasons.
  
cd po/glossary/
+
==== Prepopulate your file with translations from your glossary and other projects ====
./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot
+
The basic idea is decribed in [https://www.gnu.org/software/gettext/manual/html_node/Compendium.html#Compendium Gettext Manual: Using Translation Compendia]. Your translator tools might already support compendia. If not, i.e you are using a plain text editor, here is the manual way:
  
If your .po glossary file does not exist, use this gnc-glossary.pot file to
+
There are in total 3 programms in use:
create it:
+
:;msgcat: Concatenates and merges the specified PO files.
 +
:;msgmerge: Merges two or more Uniforum style .po files together.
 +
:;msgattrib: Filters the messages of a translation catalog according to their attributes or manipulates their attributes.
  
cp gnc-glossary.pot XXXX.po
+
:;Example: To merge a compendiumn like our glossary:
 +
<SyntaxHighlight lang="sh">
 +
cd ${SRCDIR}/po
 +
# Gettext manual's suggestion to merge compendia without old po file:
 +
msgmerge --compendium glossary/${LL}.po -o ${LL}.po /dev/null ${BUILDDIR}/po/gnucash.pot
 +
# Perhaps better:
 +
msgmerge -U ${LL}.po --compendium glossary/${LL}.po ${BUILDDIR}/po/gnucash.pot
 +
</SyntaxHighlight>
  
If your .po glossary file does exist, use the msgmerge program to update it:
+
===== GOffice =====
 +
Gnucash has borrowed a couple of source files from [https://github.com/GNOME/goffice goffice]. Those files contain a number of translatable strings. The goffice translation teams have already put effort in translating those in many languages. To reduce our translation effort, the script linked in [[I18N#Borrowing Code]] can be used to import these translations into our own po files.
  
/usr/bin/msgmerge -o XXXX.po XXXX.po gnc-glossary.pot;
+
If the goffice part for your language is incomplete, you might consider to offer them to update their file with your work.
  
Now, open your language's glossary file and translate it completely.
+
===== GTK3 =====
 +
Stock buttons became deprecated in their version 3.10. They included:
 +
# a label with mnemonic,
 +
# for which the translation was already done in the gtk domain,
 +
# a unique icon was associated.  
  
=== Terms missing or inadequate in the glossary file ===
+
So they are no longer used since gnucash 3.0. We use still the same labels, but the GTK translation is not directly used.
  
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'''.
+
You can save some work by merging the po file of your language from GTK3, i.e. from https://gitlab.gnome.org/GNOME/gtk/tree/gtk-3-24/po into your gnucash po file.
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:
+
:;Example: To merge fitting translations from GOffice and GTK:
* <code>./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot</code> will generate a new gnc-glossary.pot,
+
<SyntaxHighlight lang="sh">
* run above ''msgmerge'' command for your XXXX.po and check it for the new msg,
+
#Example to merge common parts from po files in GOffice and GTK
* 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==
+
# Variant A: in single steps to watch their results
 +
## 1. join 3. party translations
 +
msgcat --use-first -o tmp.po ${LL}.po ${GOFFICEPATH}/po/${LL}.po ${GTKPATH}/po/${LL}.po
 +
## 2. Remove unused messages. Authoritativ is gnucash.pot:
 +
msgmerge tmp.po ${BUILDDIR}/po/gnucash.pot | msgattrib --no-obsolete > {$LL}.po
 +
rm tmp.po
  
To find out who is the last person to work on your language, look near the
+
# Variant B: in one command:
top of the po/XXXX.po file which corresponds to your language.   If your
+
msgcat --use-first ${LL}.po ${GOFFICEPATH}/po/${LL}.po ${GTKPATH}/po/${LL}.po | \
language does not have a .po file available, see the next section.
+
msgmerge ${BUILDDIR}/po/gnucash.pot | \
 +
msgattrib --no-obsolete > {$LL}.po
 +
</SyntaxHighlight>
  
The beginning of your .po file should look something similar to this:
+
==== Adjust po/CMakeLists.txt ====
 +
Also include your language code into the ''NEW_LINGUAS variable'' in the '''CMakeLists.txt''' file in the ''po folder'' of your ''source directory'':
  
# Localization for Portuguese-Brazil
+
<SyntaxHighlight lang="sh" highlight="8">
# Copyright (C) 2003 Free Software Foundation, Inc.
+
# Set of available languages:
# Jon Lapham <lapham@extracta.com.br>, 2003
+
# * managed at the Translation Project (TP):
# Jose Carlos Nascimento - <joseca@psabs.com>, 2001.
+
set (TP_LINGUAS az ca cs da eu fa ja nl rw sk sr sv tr uk zh_CN)
#
+
# * already marked as external at TP:
msgid ""
+
set (GC_LINGUAS ar bg de el en_GB es fi fr gu he hi hu it kn ko lt lv mr nb ne pl pt pt_BR ro ru ta te ur vi zh_TW)
msgstr ""
+
# * New or unmarked: The release manager should announce them to TP
"Project-Id-Version: GnuCash 1.8.3\n"
+
# and when listed there move in the respective group above.
"POT-Creation-Date: 2003-05-16 16:42-0300\n"
+
set (NEW_LINGUAS as brx doi es_NI kok kok@latin ks mai mni mni@bengali)
"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
+
set (ALL_LINGUAS ${TP_LINGUAS} ${GC_LINGUAS} ${NEW_LINGUAS})
and ask what you can do to help.  This is important because if there already
+
</SyntaxHighlight>
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==
+
''CMakeLists.txt'' is a file, which controls the configuration of the build process. So after changing it, you have to '''rerun cmake'''. Some IDEs like [[Eclipse]] will do it automagical for you.
  
Before you begin actual translation work, you should update the gnucash.pot
+
As part of the build your <tt>LL.gmo</tt> file is generated in the po directory of your build tree. Finally ''make install'' will copy it to the place, where it will be found at runtime. If you forget one of the steps, your translated language will not appear.
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
+
Continue with [[#Translating the .po file]].
  
If make complains "<tt>make: *** No rule to make target `<path/to/missing-source-file>', needed by `gnucash.pot'.  Stop.</tt>", you should run
+
=== Update an existing .po file ===
make clean
 
and then retry "<code>make pot</code>". That can happen because we sometimes remove obsolete files.
 
  
Now go in the po directory:
+
Before you begin actual translation work, you should update the gnucash.pot
cd po
+
file and use this to update your .po file.  This process will insure that
 +
you have the latest translatable strings.
  
If your language file does not exist, see the next section for creating a new language file.
+
If your language file ''already exists'', update it using the ''msgmerge'' program. This will move the old translations of unchanged strings in the new file: <syntaxhighlight lang="sh">
 +
msgmerge --previous -U LL.po gnucash.pot
 +
</syntaxhighlight>
 +
;Note: If you had choosen a ''separate build directory'', e.g. <tt>.build</tt>, adjust the path in above command: <syntaxhighlight lang="sh">
 +
cd ${SRCDIR}/po # adjust ${SRCDDIR}
 +
export BUILDDIR=../build # adjust this
 +
msgmerge --previous -U LL.po ${BUILDDIR}/po/gnucash.pot
 +
</syntaxhighlight>
 +
;Note for maintainers: To update all .po files: <syntaxhighlight lang="sh">
 +
cd ${SRCDIR}/po # adjust ${SRCDDIR}
 +
export BUILDDIR=../build # adjust this
 +
for i in *.po; do echo -n "$i:"; msgmerge --previous -U $i ${BUILDDIR}/po/gnucash.pot; done
 +
</syntaxhighlight>
  
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:
+
;Separate commits for "noise" and real work: You should now run <tt>git commit</tt> or ''create a patch'' <tt>"L10N:<locale>: Merge recent template"</tt>.
 +
: This will contain only the "noise" from the updated pot file as usually many line numbers change.
 +
:; Diff example after msgmerge: <syntaxhighlight lang="diff">
 +
#. Business options
 +
-#: ../src/app-utils/app-utils.scm:303
 +
-#: ../src/business/business-gnome/gncmod-business-gnome.c:117
 +
+#: ../src/app-utils/app-utils.scm:322
 +
+#: ../src/business/business-gnome/gncmod-business-gnome.c:119
 +
msgid "Business"
 +
msgstr "Geschäft"
 +
</syntaxhighlight>
 +
:Hiding your real changes in hundreds of such sections will make it really hard for your coworkers to find them.
  
/usr/bin/msgmerge -o LL.new.po LL.po gnucash.pot
+
After having done your [[#Translate the strings|translation]] you [[#Submitting|submit]] a second commit or patch containing your actual work <tt>"Update <locale>.po"</tt>.
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.
+
You should also do it, if your current translation tool uses '''other format settings''' like line breaks as the previous tool. In this case just open the file, save it and <tt>git commit</tt> or ''create a patch'' <tt>"L10N:<locale>: Preparation: Reformating"</tt>.
 +
:;Example in KBabel format: <syntaxhighlight lang="po">
 +
#: ../src/app-utils/business-prefs.scm:33
 +
msgid "The format string to use for generating customer numbers. This is a printf-style format string."
 +
msgstr "Используемая строка форматирования для создания номеров клиентов. Её формат соответствует printf."
 +
</syntaxhighlight>
 +
:;Example in PoEDit format: <syntaxhighlight lang="po">
 +
#: ../src/app-utils/business-prefs.scm:33
 +
msgid ""
 +
"The format string to use for generating customer numbers. This is a printf-"
 +
"style format string."
 +
msgstr ""
 +
"Используемая строка форматирования для создания номеров клиентов. Её формат "
 +
"соответствует printf."
 +
</syntaxhighlight>
  
== Build a new .po file ==
+
;Review the file header:
 +
* <tt>Project-Id-Version should be ''GnuCash {{Version}}'' and
 +
: <tt>POT-Creation-Date</tt> should be recent. If they are not, you probably forgot [[#Get a fresh template]] or [[#Updating an existing .po file]].
 +
* The <tt>PO-Revision-Date</tt> should be >= <tt>POT-Creation-Date</tt>.
 +
Some, but not all tools will do this reliably for you.
  
If there is no .po file for your language, then you can start a new one. Start by copying the file <tt>gnucash.pot</tt> into a work file named <tt>LL.po</tt>, where <tt>LL</tt> 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.
+
=== Translating the .po file ===
  
Each message to translate is then given in turn in the PO file. For example, an untranslated entry might be:
+
Finally.  You are ready to do some translating!
  
#: lib/error.c:88
+
The .po source files are plain text files.
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:
+
==== Tools ====
 +
Some ''plain text editors'' offer a specific ''syntax highlighting for .po file''s, but there are also specific tools you can use:
 +
* ''Emacs'' has the po-mode to edit po files.
 +
* [https://de.wikipedia.org/wiki/Geany Geany], an editor with sytax highlighting and a little bit more
 +
* [{{URL:wp}}wiki/Gtranslator 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. Update this, if you know it is fixed.
 +
* ''KBabel'' was another recommended tool, see ''Lokalize''.
 +
* ''Lokalize'' is the successor of KBabel in KDE4.
 +
* ''[https://poedit.net/ Poedit]'' to finish the PO file edit and build.
 +
: [{{ListURL}}/pipermail/gnucash-devel/2018-September/042808.html Version 2.1.1 had issues]
 +
* ''[https://poeditor.com/ POEditor]'' can be used online.
 +
* ''[https://docs.translatehouse.org/projects/translate-toolkit/en/latest/index.html translate-toolkit]'' is a python based suite.
 +
* Wikipedia:
 +
** [{{URL:wp}}List_of_translation_software List of translation software]
 +
** [{{URL:wp}}Comparison_of_computer-assisted_translation_tools Comparison of computer-assisted translation tools]
 +
(feel free to add more tools here)
  
  #: lib/error.c:88
+
==== Gettext source (.po) file format ====
msgid "Unknown system error"
+
===== Record Format =====
msgstr "Unbekannter Systemfehler"
+
A record in a po file has the following form:
 +
<syntaxhighlight lang="po"><empty or only white-space>
 +
# translator-comments
 +
#. extracted-comments
 +
#: reference…
 +
#, flag…
 +
#| msgctxt previous-message-context
 +
#| msgid previous-untranslated-string
 +
msgctxt optional-message-context
 +
msgid untranslated-string
 +
msgstr translated-string
 +
</syntaxhighlight>
 +
*The ''empty or only white-space'' line is the record separator.
 +
*In ''translator-comments'' you can put your own notes.
 +
*The ''extracted-comments'' are notes from the programmers for you.
 +
* One or more ''reference''s tell you, where the message appears in the sources.
 +
* The most important ''flags'' will be explained below in [[# Common Flags]] and [[#Special characters and other tips|source language format flag]] will be explained below.
 +
* The ''previous-*'' entries will only appear, after <tt>msgmerge --previous …</tt> for fuzzy messages to show what changed.
 +
* An ''optional-message-context'' has the purpose to distinguish equal msgids with different meanings.
 +
* The ''msg*'' should explain themself above.
  
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.
+
;Example:Here is an example of translating some text into German:
  
The top of the .po file should be edited somewhat. The comments at the
+
Before:<syntaxhighlight lang="po">
top of the file should be changed to be current:
+
#: messages-i18n.c:11
 +
msgid ""
 +
"The GnuCash personal finance manager.\n"
 +
"The GNU way to manage your money!"
 +
msgstr ""
 +
</syntaxhighlight>
 +
After, the translation in the de.po file:
 +
<syntaxhighlight lang="po">
 +
#: 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!"
 +
</syntaxhighlight>
 +
You should read through every translation in the .po file at least once.
  
# Messages in Deutsch fuer GnuCash
+
===== Common Flags =====
# Copyright (C) 1999 Free Software Foundation, Inc.
+
====== Fuzzy Flag ======
# Jan-Uwe Finck <Jan-Uwe.Finck@bigfoot.de>, 1999.
+
If you see a string that has the phrase <code>#, fuzzy</code> in the flags comment above it, review the translation and confirm it by removing
 +
* the <tt>, fuzzy</tt> flag, but no other flags like <tt>, c-format</tt>,
 +
* the <tt>#| msgid</tt> lines, and in some cases
 +
* the <tt>#| msgctxt</tt> line.
 +
A fuzzy translation means that the translation will be ignored by the program.
  
Make sure that the header of your .po file contains an adjusted form, e.g. for slavian languages set nplurals=3, of this line:
+
There are at least 2 reasons for the fuzzy flag:
"Plural-Forms: nplurals=2; plural=n != 1;\n"
+
# one of the <tt>msg*</tt> programs took some guess about what the translation might be from similar msgids,
 +
# in a previous version you had a valid translation, but a programmer changed (parts of) the msgid.
  
...and that you change the "Last-translator" string to your name.
+
After you finish translating, you should not have any "<tt>#, fuzzy</tt>" strings left. Remember, a string marked as "fuzzy" means it will not be translated in the program. You can filter for fuzzy messages by running <syntaxhighlight lang="sh">
 +
cd ${SOURCEDIR}/po
 +
msgattrib --fuzzy ${YOUR_LANGUAGE}.po
 +
</syntaxhighlight>
  
Also include your language code to ALL_LINGUAS variable in configure.ca file in top level folder of source package:
+
;Example fuzzy message: <syntaxhighlight lang="po" highlight="2-3,5">
ALL_LINGUAS="bg ca cs da de el en_GB es_NI es eu fa fi fr he hu it ja ko lt lv nb ne nl pl pt_BR pt ro ru rw sk sv ta tr uk vi zh_CN zh_TW"
+
#: messages-i18n.c:35
 +
#, fuzzy, c-format
 +
#| msgid "There was an error opening the file %s."
 +
msgid "There was an error writing the file %s."
 +
msgstr "Es gab einen Fehler beim Oeffnen der Datei %s."
 +
</syntaxhighlight> Here the msgid was changed from "opening" to "writing". You need to correct the translated string, remove the line(s) with the old msgid "<tt>#| msgid …</tt>" and the 'fuzzy' flag, because only then the translation will actually appear in the program.
 +
;Example fuzzy fixed: <syntaxhighlight lang="po" highlight="2,4">
 +
#: messages-i18n.c:35
 +
#, c-format
 +
msgid "There was an error writing the file %s."
 +
msgstr "Es gab einen Fehler beim Schreiben der Datei %s."
 +
</syntaxhighlight> Notice that <code>#, c-format</code> was ''not removed''.  That is correct, you should leave that.
  
So that <tt>LL.gmo</tt> file is generated in ./po directory during ''make install'', otherwise translated language won't appear.
+
====== Format Flags ======
 +
Because parts of GnuCash were written in different programming languages, there appear at least 2 different format flags:
 +
;c-format: Format specifier: <code>%</code>
 +
: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...
 +
;scheme-format: Format specifier: <code>~</code>
 +
;Todo: Which parts of [[#Special_characters_and_other_tips]] would better stay here?
  
== Translating the .po file==
+
===== Orphaned Records =====
 +
At the end of your file you might see records like <Syntaxhighlight  lang="po">
 +
#~ msgid "Enter an Online Direct Debit Note"
 +
#~ msgstr "Online-Lastschrift eingeben"
  
Finally. You are ready to do some translating!
+
#~ msgid "Debited Account Number"
 +
#~ msgstr "Konto-Nr. des Zahlungspflichtigen"
  
Here is an example of translating some text into German:
+
</syntaxhighlight>
 +
They have no reference line. This records are no longer in use and you can remove them.
  
Before:
+
==== Translate the strings ====
#: messages-i18n.c:11
+
Each message to translate is then given in turn in the PO file. For example, an untranslated entry might be:
msgid ""
+
<syntaxhighlight lang="po">
"The GnuCash personal finance manager.\n"
+
#: lib/error.c:88
"The GNU way to manage your money!"
+
msgid "Unknown system error"
msgstr ""
+
msgstr ""
 +
</syntaxhighlight>
  
After, the translation in the de.po file:
+
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:
 +
<syntaxhighlight lang="po">
 +
#: lib/error.c:88
 +
msgid "Unknown system error"
 +
msgstr "Unbekannter Systemfehler"
 +
</syntaxhighlight>
  
#: messages-i18n.c:11
+
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.
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.
+
===== Contexts =====
If you translate a string that has the phrase "#, fuzzy" in the comments
+
;Important: With Gnucash 3.7 the first 2 forms got replaced by [[#Message Context]]. The description of the old types is only kept for some time to help updating older catalogs.
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.
+
At some places, GnuCash uses "disambiguation prefixes" in translatable strings. Here is an old explanation:
 +
{{ListURL}}/pipermail/gnucash-devel/2005-October/014236.html ; more explanation is also here: https://wiki.gnome.org/GnomeI18nDeveloperTips.
  
For example:
+
There are at least 2 ''use cases'':
 +
* '''Abbreviations''', i.e. for columns and their headers:
 +
<SyntaxHighlight lang="po" highlight="2,5">
 +
msgid "Reconciled"
 +
msgstr "Abgeglichen"
 +
:
 +
msgid "Reconciled:R"
 +
msgstr "Reconciled:A"
 +
</SyntaxHighlight>
 +
* '''Sample text''' to determinate the size of the output cell. ''Instead of a translation'' the "worst case" of expected text in your language is required here.
 +
:For the following example the german tranlators copied ''the longest path'' of account names from their business account templates as shown in the accounts tab of Gnucash: <SyntaxHighlight lang="po" highlight="2">
 +
msgid "sample:Expenses:Automobile:Gasoline"
 +
msgstr "sample:Aufwendungen 2/4:Reparatur/Instandhaltung:4805 Reparatur u. Instandh. von Anlagen/Maschinen u. Betriebs- u. Geschäftsausst."
 +
</SyntaxHighlight>
 +
:;Important: ''Keep'' the part before the colon ''untranslated''.
  
#: messages-i18n.c:35
+
Another form - without need to insert the prefix - was <SyntaxHighlight lang="po">
#, fuzzy, c-format
+
#. Translators: This string has a context prefix; the translation
msgid ""
+
#. must only contain the part after the | character.
"There was an error writing the file\n"
+
#: gnucash/gnome-utils/dialog-options.c:722
"     %s\n"
+
#: gnucash/gnome-utils/gnc-tree-view-account.c:908
"\n"
+
msgid "Column letter for 'Placeholder'|P"
"%s"
+
msgstr "P"
msgstr ""
+
</SyntaxHighlight> and became
"Es gab einen Fehler beim Oeffnen der Datei. \n"
+
<SyntaxHighlight lang="po">
"     %s."
+
#: gnucash/gnome-utils/dialog-options.c:719
 +
#: gnucash/gnome-utils/gnc-tree-view-account.c:906
 +
msgctxt "Column header for 'Placeholder'"
 +
msgid "P"
 +
msgstr "P"
 +
</SyntaxHighlight>
 +
;Tip: A tool like kdiff3 can help you to recover your previous translation.
 +
====== Message Context ======
 +
In more recently written parts we use a message context: <SyntaxHighlight lang="po" highlight="2-3">
 +
#: libgnucash/app-utils/gnc-ui-util.c:903
 +
msgctxt "Reconciled flag 'not cleared'"
 +
msgid "n"
 +
msgstr ""
 +
</SyntaxHighlight>
  
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.
+
===== Special characters and other tips =====
For example:
+
''Depending on the context'' a few characters have a special meaning and need some special treatment:
 +
;"#" (hash): In English it is often used as abbreviation for "Number". You should replace it by "No.", "Nr." or whatever is common in your language.
 +
;"_" (underline): In ''menu and dialog entries'' the following character will become the '''accelerator''', '''mnemonic''' or '''hotkey''', which can be used together with a superkey [ctrl] or [alt] to jump to the entry. While in [[GTK2]] they have always been visible, in [[GTK3]] they appear only after holding the superkey. More specific under ''Linux'' you reach a main '''menu''' entry with <code>[alt]+[key]</code> and its submenus and other menu entries with <code>[key]</code>. In '''dialogs''' always use <code>[alt]+[key]</code>.
 +
: The terminology is not unique here: while
 +
::[[#Desired|msgfmt]] has a <code>--check-accelerator</code> option and
 +
::DocBook uses <accel> tag for ''a letter used with a meta key'' and <shortcut> for ''a key combination'', but
 +
::GTK+ distinguishes the underline marked character of the label as ''mnemonic'' and the hotkeys like F1 for Help as ''accelerator''.
 +
: So the key should be ''unique in its context'' and you should control it by [[#Running GnuCash]] with your file after [[#Compile & Install]].
 +
::''wrong:''
 +
:::"do _this" # Hotkey: t
 +
:::"do _that" #  Hotkey: t => not directly reachable
 +
::''right:''
 +
::: "do th_is" # Hotkey: i
 +
:::"do th_at" # Hotkey: a
 +
::That is one of the reasons why you should [[#Optional Compile & Install|run the program with your translation]]: to see duplicate accelerators.
 +
::;Characters to avoid:
 +
:::Already used on buttons like in English: '''C'''lose, '''H'''elp. Others depend on the context.
 +
:::Characters breaking the baseline like in latin script: '''j''','''p''','''q''','''y'''. At least in some fonts the underline becomes invisible - leaving the user clueless.
 +
:;In the headers of exported files: here it is used to link multiple words to one identifier together. Example:
 +
<syntaxhighlight lang="po">
 +
#: ../src/import-export/csv-exp/csv-tree-export.c:155
 +
msgid "full_name"
 +
msgstr "Vollständige_Bezeichnung"
 +
</syntaxhighlight>
  
#: messages-i18n.c:35
+
;"\" (backslash): It is the escape character in many programming languags. The following character has a special meaning like e.g.:
#, c-format
+
:;"\n" (New line): The most often used special character in our strings. If msgid contains "\n" keep the layout and add them to msgstr too - at the same places.
msgid ""
+
:;"some \"quoted\" text": Because " terminates the messages, you must precede it by a backslash inside of the messages or use other quoting characters like:
"There was an error writing the file\n"
+
::*"some 'quoted' text"
"     %s\n"
+
::*"some »quoted« text"
"\n"
+
::*"some „quoted” text"
"%s"
+
::You are free to use the conventions which are common or suggested in your language, but stay consistent. For that purpose you should add a translator comment about the convention at the beginning of the file for better cooperation.
msgstr ""
+
:Use <tt>"\\"</tt> to print a backslash.
  "Es gab einen Fehler beim Schreiben der Datei. \n"
+
;"%" (percent): In C based programming languages "%" marks the beginning of a '''format specifier''', e.g. "%d6" means insert the next variable here ''in decimal format with 6 digits''. Such format specifiers should be copied into your translated message, at the appropriate spot for your language. Boost's list of format flags for date and time is available at https://www.boost.org/doc/libs/release/doc/html/date_time/date_time_io.html#date_time.format_flags.
  "     %s."
+
:;Non-ASCII digits: As a special feature for Farsi (Persian) and maybe Arabic, translators can insert an ‘I’ flag into numeric format directives. For example, the translation of "%d" can be "%Id". The effect of this flag, on systems with GNU libc, is that in the output, the ASCII digits are replaced with the ‘outdigits’ defined in the LC_CTYPE locale category. On other systems, the gettext function removes this flag, so that it has no effect.
 +
:;Note: If a string is marked with c-format and has a % mark that does '''not''' start a format specifier, [{{BugURL}}/enter_bug.cgi?product=GnuCash&component=Translations file a bugreport] and tell the developers the location of the string (the lines above the msgid). The developers should fix this in the code. One way to do so is to insert a comment containing '''<tt>xgettext:no-c-format</tt>''' before the gettect call.
 +
::In order to continue without having to wait for the developers' fix to propagate you can remove the <tt>c-format</tt> flag from the <tt>#,</tt> comment line above. If no other flags are in the line, simply remove the line.
 +
:* To output "%" if a string contains format specifiers, use "%%" in your string.
 +
:;Reordering parameters: Assume a string <tt>"In %d cases the result will be %d."</tt>, but in your language you would prefer to write <tt>"%d will be the result in %d cases."</tt> Now you would get the wrong numbers.
 +
::;Solution: Insert the ordinal number of the parameter, followed by "$" in the format specifier: <tt>"%2$d will be the result in %1$d cases."</tt>.
 +
;"~" (tilde): like "%", but for <code>scheme-format</code>. The basic scheme-format uses ~a or ~s to format subsequent variables within code and should be copied in the translated message, in the same order. Guile's <tt>(ice-9 format)</tt> does reordering with the ~@* and ~#* arguments, but it's a bit tricky to use:<syntaxhighlight lang="scheme">
 +
  (format #t "~@*1~a's ~@* from ~@*2~a to ~a" "Balance Sheet" "Yoyodyne Pty" "1 Oct 2018" "30 Sept 2019")
 +
</syntaxhighlight> would print <syntaxhighlight lang="console">
 +
  Yoyodyne Pty's Balance Sheet from 1 Oct 2018 to 30 Sept 2019
 +
</syntaxhighlight>
 +
:;Note: ~a will insert a contents using "human readable" <tt>(display var)</tt> whereas ~s will insert contents using <tt>(write var)</tt>. This is an important difference which means ~a and ~s cannot be interchanged.<ref>https://www.gnu.org/software/guile/manual/html_node/Scheme-Write.html</ref>
 +
<References />
 +
;"{''num'',''optional other specifiers''}": this is a format specifier for C++ code. You cat either copy it verbatim somewhere in your translated message or you may [https://www.boost.org/doc/libs/release/libs/locale/doc/html/localized_text_formatting.html adapt it to your language].
 +
;"&" (ampersand): is the starting character of [{{URL:wp}}Character_encodings_in_HTML HTML encoding], which is used in some reports. E.g. <syntaxhighlight lang="html">&nbsp;</syntaxhighlight> means NonBreakableSpace.
 +
;"<" (less): is the starting  charcter of tags in several markup languages. E.g. <syntaxhighlight lang="html"><b>Text</b></syntaxhighlight> results in bold '''Text'''.
 +
;See also: [[GUI Guidelines]] is the related programmers view.
  
Notice that the comment "c-format" was not removed. That is correct, you
+
===== Almost Done =====
should leave that.
+
If you are almost done it becomes harder to find the last untranslated messages. Then you can use <syntaxhighlight lang="sh">
 +
msgattrib --untranslated ${LL}.po
 +
</syntaxhighlight> and then search your file for the content of the msgid.
  
When you see the comment "c-format", it means that the format codes in the  
+
==== Check syntax and statistics of your .po file ====
translatable string are referring to C formatting codes. So, '%s' means text,  
+
===== Required =====
'%d' means an integer, etc...
+
<syntaxhighlight lang="sh">
 +
msgfmt -c --statistics ${LL}.po
 +
</syntaxhighlight>
 +
If that program reports one or more ''fatal errors'' for your language, you should review the criticized lines of your file.
 +
:;Tip: A successful call will create a file <tt>messages.mo</tt>. If you are not using a build environment, you can move that file to
 +
::;Linux: <tt>[[Building On Linux#Locations to which GnuCash may be installed|${PREFIX}]]/share/locale/${LL}/LC_MESSAGES/gnucash.mo</tt>
 +
:: and restart gnucash to test the program with your translation.
 +
===== Desired =====
 +
In a second run you might wish to see, where you forgot to add an [[#Special characters and other tips|accelerator]]:
 +
<syntaxhighlight lang="sh">
 +
msgfmt -c --check-accelerators="_" --statistics ${LL}.po
 +
</syntaxhighlight>
 +
The users will love you if you fix them, too.
  
=== Current status ===
+
==== Current status ====
 
See [[Translation Status]] for the current status of the project with respect to translation contributions.
 
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
+
To see some over all statistics how many strings are translated, you can run
 
  for i in *.po; do echo -n "$i:"; msgfmt -c --statistics $i;done
 
  for i in *.po; do echo -n "$i:"; msgfmt -c --statistics $i;done
 
in your po directory.
 
in your po directory.
  
=== Tools ===
+
==== Priority ====
* Additional Tools: You can use ''Poedit'' ( get it here: http://www.poedit.net/download.php ) to finish the PO file edit and build.
+
As you might have noticed, the po file for GnuCash is rather big by containing more than 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.
* ''[https://poeditor.com/ POEditor]''can be used online
 
* ''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:
 
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.
 
* '''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.
+
:;Tip: If you wish to see the string from a *.glade.h file in it's context, but don't know, where it is hidden in gnucash, you can open the file <tt>gtkbuilder/*.glade</tt> with Gnomes interface builder [https://glade.gnome.org/ Glade].
 +
* '''Low Priority:''' Strings from all '''*.schemas.h''' files will '''not''' appear in the gnucash UI. Instead, they are shown only inside the  
 +
:* Linux: ''dconf-editor'',
 +
:* macOS: ''defaults'' or
 +
:* Windows: ''regedit'' program when the user wants to set particular [[Glossary#G|GSettings]] keys of GnuCash. You can safely consider the .schemas.h strings with lower priority than the others.
 +
**  '''Register2 feature''' is a stalled developement. The strings are only visible, if you [[#configure]]<tt> --enable-register2</tt>. Some, but not all strings are marked with a "Register2 feature" comment.
  
 
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.
 
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.
Line 374: Line 849:
 
* 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'''.
 
* 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 ===
+
=== Testing and submitting your translations ===
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 [http://www.gtk.org/api/2.6/glib/glib-I18N.html#Q-:CAPS 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 [http://www.gnu.org/software/hello/manual/gettext/Contexts.html Gettext Manual: Contexts] for details.
 
 
 
== Testing and submitting your translations==
 
  
 
You must check that your new translations are programatically correct (ie:  
 
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
 
that there are no unclosed quotes, etc).  To do this, use the msgfmt program
  
  /usr/bin/msgfmt -c --statistics XXXX.po
+
  msgfmt -c --statistics LL.po
 +
 
 +
Above call will report most important errors in your .po file and ''must not fail'', while the call below
 +
msgfmt -c --check-accelerators="_" --statistics LL.po
 +
whill additionally check if you missed some keyboard accellerators aka hotkeys.
  
This will report any errors in your .po file if it finds them.
+
;Note for developers: Another python based tool is '''i18nspector''' - checking tool for gettext POT, PO and MO files. It is stricter and shows also warnings about expected entries which our .pot file is currently missing. That can be discussed e.g. in [[#Background]].
  
 
If you want to see your translations within a running version of gnucash,
 
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
+
simply place your .po file in the po/ directory of your local gnucash repository (which
 
you have previously installed) and from within the po/ directory type (you
 
you have previously installed) and from within the po/ directory type (you
 
may need to be root to do this):
 
may need to be root to do this):
Line 419: Line 871:
 
Now you can run gnucash with your new translations:
 
Now you can run gnucash with your new translations:
  
  LANG=XXXX /opt/gnucash-svn/bin/gnucash
+
  LANG=XXXX /opt/gnucash-git/bin/gnucash
 +
 
 +
To review the schema strings you can use
 +
:;since 2.6: dconf-editor
 +
:;until 2.4: gconf-editor.
  
  
 
==== Alternative Way with Poedit ====
 
==== Alternative Way with Poedit ====
  
If you use Poedit while working on .po file, you would notice that it saves file in .mo format, the very format that GnuCash uses itself. So one would just need to copy this LL.mo file into appropriate subdirectory under /opr/gnucash-svn:
+
If you use Poedit while working on .po file, you would notice that it saves file in .mo format, the very format that GnuCash uses itself. So one would just need to copy this LL.mo file into appropriate subdirectory under /opt/gnucash-git:
   cp LL.mo /opt/gnucash-svn/share/locale/LL/LC_MESSAGES/gnucash.mo
+
   cp LL.mo /opt/gnucash-git/share/locale/LL/LC_MESSAGES/gnucash.mo
  
The only thing that needs to be changed here is LL which stands for your country code (ka Georgian, de German etc). The rest is as in above method:
+
The only thing that needs to be changed here is LL which stands for your language code (ka Georgian, de German etc). The rest is as in above method:
  LANG=XXXX /opt/gnucash-svn/bin/gnucash
+
  LANG=XXXX /opt/gnucash-git/bin/gnucash
  
 
=== Submitting ===
 
=== Submitting ===
When you are happy with the new translation file, email a gzipped version
+
Only if
of it to the gnucash-devel [[Mailing Lists|mailing list]].
+
* you want to send your file to the Translation Project or
 +
* it did not exist before and you want to send it via mailing list, create a gzipped version of it:
 +
<SyntaxHighlight lang="sh">gzip XXXX.po</SyntaxHighlight>
 +
:Do the same with your [[#The glossary file]].
 +
 
 +
In all other cases just push your commit ([[Git#Pull Requests]]) or upload the [[Git#Patches]] of the files.
 +
There should be one commit/patch containing the noise as described in [[#Update an existing .po file]] and a second one containing your actual work.
  
gzip XXXX.po
+
Then follow [[#How to submit changes directly to GnuCash]].
(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.
+
Alternatively, you could submit the finished translation via the GNU Translation Project. See the instructions on {{URL:TP}} 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.
 
See [[Translation Status]] for the current status of the project with respect to translation contributions.
  
See also http://lists.gnucash.org/pipermail/gnucash-devel/2009-January/024700.html
+
See also {{ListURL}}/pipermail/gnucash-devel/2009-January/024700.html [FIXME: obsolete?]
  
== Problems==
+
==== Committers ====
 +
* Check in which branch the translation should be submitted: [[Translation_Status]]
 +
* Did you get [[#The glossary file]], too?
 +
* Ideally [[#Updating an existing .po file]]
 +
* Checks:
 +
**[[#Check_syntax_and_statistics_of_your_.po_file]]!
 +
*:Notify the statistics for the commit message.
 +
** The Python tool <tt>i18nspector</tt> finds many additional errors, particular bad header lines. But its language list is incomplete as it knows not many 3-letter-languages.
 +
**Some common mistakes:
 +
::;msgid "translator-credits": should contain at least the "Last-Translator:" from the header.
 +
::;msgid "gnucash-icon": do not translate, we have only one.
  
=== intl/Makefile is already registered ===
+
* If the language is ''new''
When you see this error message during autogen.sh run:
+
** [[#Adjust po/CMakeLists.txt]] already done?
 +
** and not handled by the [[#translationproject.org]], they need a '''note about the external handling'''. Else it can happen e.g. as of 2015-03  {{URL:TP}}team/ar.html shows: <syntaxhighlight lang="console>
 +
gnucash 2.6.5 0 / 4628
 +
</syntaxhighlight>
 +
::If you there click on 2.6.5 you will get a fresh gnucash-2.6.5.pot, while we have already an ar.po with 2031 translated and 4 fuzzy messages. By contrast on the as external marked {{URL:TP}}team/de.html, you see: <syntaxhighlight lang="console>
 +
gnucash 2.6.5 unknown external
 +
</syntaxhighlight>
 +
::and will not get a new pot file.
 +
::But we can bundle this notes with the release announcement, if you add the language to [[Release Process#TP Status changes]].
 +
* On committing add the name and email address of the last translator from the file as author, e.g.
 +
<syntaxhighlight lang="sh">
 +
git commit --author="Lieutenant Worf <lt.worf@starfleet.org>" --message="L10N:tlh[: optional status or other details]
  
configure.in:1219: error: `intl/Makefile' is already registered with
+
4677 translated messages." # << The msgfmt statistics
AC_CONFIG_FILES.
+
</syntaxhighlight>
autoconf/status.m4:844: AC_CONFIG_FILES is expanded from...
+
* If you check in a new language, remove a language or see the status of the language changes from partial to (almost) complete, update the numbers in ''<sect2 id="oview-featuresintl2">'' in file '''guide/C/ch_oview.xml''' of ''gnucash-docs''.
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:
+
=== Problems===
svn revert configure.in
 
  
=== Gtk-CRITICAL messages ===
+
==== 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!
 
'''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!
  
Line 469: Line 946:
 
To do this, you need to run gnucash under gdb:
 
To do this, you need to run gnucash under gdb:
  
  LANG=XXXX /opt/gnucash-svn/bin/gnucash-env gdb /usr/bin/guile
+
  LANG=XXXX /opt/gnucash-git/bin/gnucash-env gdb /usr/bin/guile
  
 
Then, from within gdb, issue:
 
Then, from within gdb, issue:
  run -e main -s /opt/gnucash-svn/libexec/gnucash/overrides/gnucash --g-fatal-warnings
+
  run -e main -s /opt/gnucash-git/libexec/gnucash/overrides/gnucash --g-fatal-warnings
  
Eventually, gnucash should crash (becuase of the --g-fatal-warnings  
+
Eventually, gnucash should crash (because of the --g-fatal-warnings  
 
directive), when it does, issue from within gdb:
 
directive), when it does, issue from within gdb:
  
Line 504: Line 981:
 
Remember that the translations must contain the proper underscores.
 
Remember that the translations must contain the proper underscores.
  
===File accesses===
+
==== Watch File accesses ====
 
To follow gnucash as it access files,  
 
To follow gnucash as it access files,  
  strace /opt/gnucash-svn/bin/gnucash
+
  strace /opt/gnucash-git/bin/gnucash
 +
 
 +
=== Thank You ===
 +
Thanks so very much to all the translators for their hard effort and
 +
excellent work.
  
 
== How to translate the Windows Installer==
 
== How to translate the Windows Installer==
 +
See [[Windows Installer Translation]].
  
Follow the instructions in the [https://lists.gnucash.org/pipermail/gnucash-devel/2009-January/024535.html this thread].
+
== Check Files in Repo gnucash's doc Directory ==
 +
;Note: The content of this directory got some cleanup by <s>[{{BugURL}}/show_bug.cgi?id=797111 bug 797111]</s>.
  
== Check doc/README-* ==
+
In theory one could create localized man pages (<command>.<man-section>[.in]). But their content is almost the same as <tt><command> --help</tt>, which are translated for <tt>gnucash</tt> and <tt>gnucash-cli</tt>.
 +
;Task: We should use gettext also  in the perl modules.
  
The following filepatterns in doc/ are of interest:
+
* If you add files add them to <tt>set(doc_DATA ...)</tt> in [https://github.com/Gnucash/gnucash/blob/maint/doc/CMakeLists.txt CMakeLists.txt].
* 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.
+
== Translating the GnuCash Guide and Help==
 
 
'''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? --[[User:Fell|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:
 
This section describes the actions needed to translate the manuals. There are currently 2 parts:
* ''Concept '''Guide''' and Tutorial'': This is an introduction in the basic principles of double entry accounting and their application in GnuCash. This text is really useful for new users. Even though the text is rather old, it still matches most ways of how GnuCash works.
+
* ''Tutorial and Concept '''Guide''''': This is an introduction in the basic principles of double entry accounting and their application in GnuCash. This text is really useful for new users.  
* '''Help''': This is the context sensitive help system. Unfortunately, many recent changes in the program have not been updated in these help texts, so this document is probably largely outdated and so of less use.
+
* '''Help''': This is the context sensitive help system.  
  
Both texts contain various useful parts and also various outdated which are less useful. If you are interested in translating those documents, please make a decision for yourself whether you want to "only" translate the existing text or also improve and cross-check the text with the actual status in the program in your language. It is less effort to "only" translate the text, but you also run into the risk of doing unnecessary work if you translate explanations which are no longer correct. It might be more effort to create a new text in your language, using the English text only as an inspiration, but it will surely lead to a more useable and more helpful documentation. We, the programmers, encourage you to do the latter and create a new text in your language. As you are the one doing the work, the decision is up to you.
+
If you are interested in translating these documents, please decide whether you want ''only'' to translate the existing text or whether you want also to improve and cross-check the text with the actual status in the program in your language. It is less effort only to translate the text, but you also run into the risk of doing unnecessary work if you translate explanations which are no longer correct. It might be more effort to create a new text in your language, using the English text only as an inspiration, but it will surely lead to more useable and more helpful documentation. We, the programmers, encourage you to do the latter and create a new text in your language. As you are the one doing the work, the decision is up to you.
  
 
Both documents consist of  
 
Both documents consist of  
* text files in a format called [http://en.wikipedia.org/wiki/DocBook DocBook], where the complete document is split into a collection of xml files by chapter, and
+
* '''text''' files in an XML format called [{{URL:wp}}DocBook DocBook], where the complete document is split into a collection of xml files by chapter, and
* pictures: Those are png files in the subdirectory figures/. The xml files will contain links to the png files where they should appear in the text.
+
* '''images''':
At the beginning you might wish to concentrate on the text. If desired, you could link the pictures from C/figures.
+
** In the few ''scalable vector graphics'' (SVG) you can replace the text in you localized file.
 +
** But most are ''screenshots'' stored as [{{URL:wp}}Portable_Network_Graphics Portable Network Graphics] (png) files in the subdirectory figures/. The xml files will contain links to the png files where they should appear in the text.
 +
:;See also: [[Documentation Update Instructions#Screenshots and Images]]
 +
At the beginning you might wish to concentrate on the text. If desired, you could link the english pictures from <tt>C/figures</tt>.
 +
 
 +
You can find an introduction to DocBook in [https://tdg.docbook.org/tdg/{{DocbookVersion}}/ch02.html Creating DocBook Documents].
  
 
Please use a ''unified terminology'': The translator of the program messages should have created [[#The glossary file]] for the translations of the key wordings in the program. Please make sure to use the same terms in the documents, too.
 
Please use a ''unified terminology'': The translator of the program messages should have created [[#The glossary file]] for the translations of the key wordings in the program. Please make sure to use the same terms in the documents, too.
  
=== Prerequisite ===
+
You can check the [{{BuildURL}}/docs/ nightly builds] - in particular after your updates were committed.
 +
 
 +
=== Prerequisites ===
  
 
==== Linux ====
 
==== Linux ====
  
In addition to the software for running autogen.sh, the following additional software is needed for the development on Linux. From the [http://svn.gnucash.org/repo/gnucash-docs/trunk/README gnucash-docs/README] file as of 2012-09-24:
+
In addition to the software for running autogen.sh, the following additional software is needed for the development on Linux. From the [https://github.com/Gnucash/gnucash-docs/blob/maint/README gnucash-docs/README] file as of 2019-02-19:
  
* libxml2/libxslt
+
:* libxml2
:'''Note:''' ''xsltproc'' is needed, which is usually part of ''libxslt'', but debian split it in two separate packages, where xsltproc depends on libxslt.
+
:* libxslt [Debian packed the required xsltproc in a separate package,  
* docbook-xsl
+
::          which depends on libxslt]
For '''viewing''' under ''Linux'':
+
:* docbook-xsl
 
:* rarian or
 
:* rarian or
:: scrollkeeper >=0.3.4 (its ancestor)
+
:: scrollkeeper >=0.3.4 (its ancestor)
:* yelp (the ''context sensitive'' GNOME help viewer) or
+
:* yelp (for viewing)
:: any HTML browser, but that will not be called from inside GnuCash
 
  
Additonal Requirements for Generating '''PDF''':
+
:Optional:
 +
:* gnome-doc-utils (contains <tt>xml2po</tt> for the use of po editors like in the it translation)
  
* Apache fop  >= 0.95
+
:Additional Requirements for Generating Mobipocket:
** fop-ttfreader    ('''non-latin PDF''')
+
:* Calibre (https://www.calibre-ebook.com/)
*** '''Japanese PDF''':
 
**** japanese-mincho-ttf (default is ipaexm.ttf)
 
**** japanese-gothic-ttf (default is ipaexg.ttf)
 
  
Additional Requirements for Generating '''Mobipocke'''t:
+
:Additional Requirements for Generating chm:
 +
:* Mingw (http://www.mingw.org)
 +
:* Html Help Workshop (https://www.microsoft.com/en-us/download/details.aspx?id=21138 for Win XP - 8)
  
* Calibre (http://www.calibre-ebook.com/)
+
:Additional Requirements for Generating PDF:
 +
:* Apache fop  >= 0.95
 +
:For the Japanese PDF, Japanese fonts are included. If you want to use other Japanese fonts you can use the --with-japanese-fonts-dir, --with-japanese-mincho-ttf, and --with-japanese-gothic-ttf configure options to select them. fop's TTFReader can't, as of version 1.1 anyway, handle OpenType fonts.
  
'''Note for wiki editors:''' Keep above section in sync with [http://svn.gnucash.org/repo/gnucash-docs/trunk/README gnucash-docs/README].
+
'''Note for wiki editors:''' Keep above section in sync with [https://github.com/Gnucash/gnucash-docs/blob/maint/README gnucash-docs/README]
  
 
==== Other Operating Systems ====
 
==== Other Operating Systems ====
Line 571: Line 1,057:
 
----
 
----
  
===== MacOSX =====
+
===== macOS =====
 
 
At present we do not know of a suitable DocBook file toolset for ''MacOSX'' though a *nix on Mac approach may / should work.  We encourage solutions so if someone could document this we would be grateful [Wm: aside is this redundant? Don't most modern Macs include *nix so instructions similar to those I have provided for Win might apply?]
 
  
 +
At present we do not know of a suitable DocBook file toolset for ''macOS'' though a *nix on Mac approach may / should work.  We encourage solutions so if someone could document this we would be grateful [Wm: aside is this redundant? Don't most modern Macs include *nix so instructions similar to those I have provided for Win might apply?]
  
 
===== Windows =====
 
===== Windows =====
Line 580: Line 1,065:
 
One way of being able to edit and produce DocBook files on ''Windows'' is to use the *nix instructions under cygwin.  Instructions for obtaining a suitable toolset follow
 
One way of being able to edit and produce DocBook files on ''Windows'' is to use the *nix instructions under cygwin.  Instructions for obtaining a suitable toolset follow
  
*Get cygwin by going to http://www.cygwin.com and pressing the link for the setup-*.exe file suited to your system
+
*Get cygwin by going to https://www.cygwin.com and pressing the link for the setup-*.exe file suited to your system
 
*save it, virus scan it, etc. as you see fit then run it
 
*save it, virus scan it, etc. as you see fit then run it
 
*type "libxslt" into the search box
 
*type "libxslt" into the search box
*expand Libs and press Skip so that it shows a version for all 3 GNOME XSLT Library options, you want the most recent which it will offer by default, cygwin will work out the dependencies
+
*expand Libs and press Skip so that it shows a version for all 3 GNOME XSLT Library options, you want the most recent which it will offer by default, cygwin will work out the gndependencies
*you may follow similar steps to obtain svn, i.e. type "svn" into the search box, expand and tick the obvious candidates
+
*you may follow similar steps to obtain git, i.e. type "git" into the search box, expand and tick the obvious candidates
 
*Note: because these are *nix type text based utilities you are downloading hundreds of kiloBytes not megaBytes; relax, this isn't Windows Update, a few extra progs won't kill your system, promise
 
*Note: because these are *nix type text based utilities you are downloading hundreds of kiloBytes not megaBytes; relax, this isn't Windows Update, a few extra progs won't kill your system, promise
 
*click next at the bottom rhs and let cygwin do its stuff; this may take some time depending on connection speeds at both ends
 
*click next at the bottom rhs and let cygwin do its stuff; this may take some time depending on connection speeds at both ends
Line 595: Line 1,080:
 
:*yelp (the viewer)
 
:*yelp (the viewer)
 
*on cygwin: it isn't there; it is an old prog (last updated in 2007, I think
 
*on cygwin: it isn't there; it is an old prog (last updated in 2007, I think
:: wrong, see http://ftp.gnome.org/pub/GNOME/sources/yelp/. --[[User:Fell|Fell]] 17:21, 26 October 2013 (EDT)
+
:: wrong, see https://download.gnome.org/sources/yelp/ for the origin and https://cygwin.com/packages/summary/yelp.html for cygwin. --[[User:Fell|Fell]] 17:21, 26 October 2013 (EDT)
 
:) and should probably not be regarded as current though it may be useful if you have it on another OS
 
:) and should probably not be regarded as current though it may be useful if you have it on another OS
 
: [Wm:  
 
: [Wm:  
Line 606: Line 1,091:
 
----
 
----
 
Wm says the section above is being edited and not yet complete, see the thread "Help with help" in gnucash-devel for more info
 
Wm says the section above is being edited and not yet complete, see the thread "Help with help" in gnucash-devel for more info
 +
 +
===== Java (all OS) =====
 +
 +
[[Eclipse]] has
 +
* several Git plugins,
 +
* a C Development Tool with autotools support,
 +
* a feature rich, builtin XML editor and a few plugins like XML WYSIWYG editors
 +
or in other words, all what is needed here, available.
  
 
=== The Procedure ===
 
=== The Procedure ===
Line 611: Line 1,104:
 
First, you have to download the most recent version of the gnucash-docs package. This is done as follows:
 
First, you have to download the most recent version of the gnucash-docs package. This is done as follows:
  
# Checkout the documentation:
+
# Checkout the documentation in a directory ''gnucash-docs'':
#: <code>svn checkout <nowiki>http://svn.gnucash.org/repo/gnucash-docs/trunk</nowiki> gnucash-docs</code>
+
#: <code>git clone <nowiki>https://github.com/Gnucash/gnucash-docs</nowiki> -b maint gnucash-docs</code>
#:
+
# Create your working branch. If you plan to use pull requests, you should use unique names like ''guide-LL-chapter-x-part-n'' instead of working-branch.
# Create a new directory (if it doesn't already exist) in guide/<locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_PT.
+
#: <code>git checkout -b working-branch</code>
 +
# Create a new directory (if it doesn't already exist) in guide/<locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_PT. See [[#Naming Conventions]].
 
#:See [[Locale_Settings#IETF_language_tags]] for details.
 
#:See [[Locale_Settings#IETF_language_tags]] for details.
 
#:If your translation is the first for your language do not add a region code. So also other regions benefit from your translation.
 
#:If your translation is the first for your language do not add a region code. So also other regions benefit from your translation.
# Copy the files from guide/C into this directory.
+
#:And copy the files from guide/C into this directory:
# Add the directory you created to [gnucash-docs/]configure.in (as a new line ''guide/<language>[_<region>]/Makefile'' under AC_OUTPUT) and [gnucash-docs/]guide/Makefile.am (at the end of SUBDIRS).
+
#: <code>cp -r guide/C guide/LL</code>
# Now the real work: Edit all the xml files (see below for suitable editor programs) and translate them into your language.
+
#:;Not in latin letters written languages: They need additinal files to process printing to pdf. See <code>ja</code> or <code>ru</code> as examples.
## 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 <code>recode -d <input_encoding>..h0 l10n.xml</code>, where input_encoding might be u8 for UTF8, to get them right encoded.
+
# Add the directory you created to [gnucash-docs/]'''configure.ac''' (as a new line ''guide/<language>[_<region>]/Makefile'' under AC_OUTPUT) and [gnucash-docs/]guide/Makefile.am (at the end of SUBDIRS).
## 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.
+
# Notify git about the new directory and files. "*" is quoted by "\".
## 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.
+
#: <code>git add guide/LL/\*.\*</code>
 +
# Now the real work:  
 +
## Edit '''all the xml files''' (see [[#DocBook xml editors]] below for suitable editor programs) and translate them into your language.
 +
##* In the event the english documents get updated, it might be useful to have a comment in the header of each chapter in  the form:
 +
##: <syntaxhighlight lang="xml"><!-- Translation based on maint/master commit 1234567 2014-01-01 10:00 UTC --></syntaxhighlight>
 +
##: Then you can later view a diff between the current and that version of the english file in one window to locate the changes and adjust the translation in  another window. Some translators like to do also the translation in a graphical diff program like KDiff3 between english and their language because the <code><sectN id></code>s will synchronize the text.
 +
##* Use the same terminoloy as in [[#The_glossary_file]]. If you did not [[#Get_the_source_from_Git]], you can simply download your languages .po file from the [https://github.com/Gnucash/gnucash/tree/maint/po/glossary glossary directory at GitHub].
 +
## Adjust  '''<tt>gnucash-{guide|help}-<lang>.omf</tt>'''. This file follows [https://www.ibiblio.org/osrt/omf/ Open Metadata Framework] (OMF), a subset of the [https://dublincore.org/ Dublin Core] description for metadata. See [http://scrollkeeper.sourceforge.net/documentation/writing_scrollkeeper_omf_files/index.html Writing ScrollKeeper OMF Files] for details like mandatory standard elements. Without this file your document will not show up in ''yelp''s index page. At some point in the future we might extract this data automaticly from the docs using  [[Gnome Doc Utils]].
 +
##: Currently it is also necessary to replace in <tt>{guide|help}/<lang>/Makefile.am</tt> the "C" in both occurrences of <tt>$(docname)-C.omf</tt> by <lang>.
 +
## 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 <code>recode -d <input_encoding>..h0 l10n.xml</code>, where input_encoding might be u8 for UTF8, to get them right encoded.
 +
## In addition to the text, you need to ''recreate the image files in '''guide/C/figures''''' so that they are appropriate to your language. For details (size, style,...) see [[Documentation_Update_Instructions#Screenshots_and_Images]].
 +
### 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.
 +
### A few figures are in '''scalable vector graphic''' (svg) format. Here you can edit the files e.g. in ''Libre/OpenOffice'' and translate the strings and adjust the size.
 +
## 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, or at least ''file a bug against it'', 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 file a patch, which adds your name and email address to AUTHORS, so you will become famous. ;-) Ask to apply this latter patch also against gnucash/DOCUMENTERS because both files should have the same content. More details about editing the english text can be found in the [[Documentation Update Instructions]].  
 
##: If you file a patch against the english text, you can also file a patch, which adds your name and email address to AUTHORS, so you will become famous. ;-) Ask to apply this latter patch also against gnucash/DOCUMENTERS because both files should have the same content. More details about editing the english text can be found in the [[Documentation Update Instructions]].  
# Test that your xml files have no syntax errors by running ''xmllint'' on the '''main file''' ''gnucash-{guide|help}.xml'', e.g.:
+
# Test your xml files for syntax errors by running ''xmllint'' on the '''main file''' ''gnucash-{guide|help}.xml'', e.g.:
 
#: <code>xmllint --valid --noout gnucash-guide.xml</code>
 
#: <code>xmllint --valid --noout gnucash-guide.xml</code>
 
#: The program ''xmllint'' is part of the package '''libxml'''.
 
#: The program ''xmllint'' is part of the package '''libxml'''.
# Optional: test your work with yelp - there are autotools files, to support you:
+
#: '''Tip:''' Some ''xml aware editors'' have a menu entry like ''validate'' to run this test.
## After you copied the directory, change to the 'root' of the gnucash-docs package and run once
+
# Optional: test your work with yelp - there are build system methods to support you. The exact steps differ based on the build system you choose:
##: <code>./autogen.sh</code>.
+
## Using a terminal, go to your gnucash-docs directory<SyntaxHighlight lang="sh">
## If you want to change some default values like installation paths, run  
+
cd /path/to/gnucash-docs # replace the example path with your real path
##: <code>./configure --help</code>,
+
</SyntaxHighlight>
##: to see the available options.
+
## Make a build directory and go into it<SyntaxHighlight lang="sh">
## Run
+
mkdir build
##: <code>./configure</code> with your desired options.
+
</SyntaxHighlight>
##: '''Tip''' for ''Windows'' and ''MacOSX'', which have no Yelp: use <tt>--disable-scrollkeeper</tt>
+
## Setup a build system of choice<SyntaxHighlight lang="sh">
## After your editing of the files, run
+
# Run this for the autotools based build system (deprecated!)
##: <code>make</code>
+
./autogen.sh
##: for some additional processing.
+
cd build
## If you had choosen something with "$HOME" as prefix in your configuration, run
+
../configure --PREFIX=../install
##: <code>make install</code>,
+
# Or run this for the cmake based build system (preferred)
##: otherwise run
+
cd build
##: <code>sudo make install</code>.
+
cmake -D CMAKE_INSTALL_PREFIX=../install
## Run
+
</SyntaxHighlight>
##: <code>yelp <path/filename></code>
+
##: There are plenty of other options you can pass to either configure or cmake, but that's outside of the scope of this wiki page.
##: with the path, to where you installed the files.
+
#: The steps above only have to be run once (though running it more than once is safe). What follows can be repeated as often as needed while working on the docs.
## Repeat steps 4-6 until everything is right.
+
## To check your work while editing you can run<SyntaxHighlight lang="sh">
# 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.
+
make check
 +
</SyntaxHighlight> in the build directory. That will However check ''all'' documentation, not just the one you're working on.
 +
## If you want to check only your work a different command is needed depending on your build system. Each command starts from the top-level of the build directory and in this example we will check work on the German version of the guide:<SyntaxHighlight lang="sh">
 +
# Run this for the autotools based build system (deprecated!)
 +
(cd guide/de && make check)
 +
# Or run this for the cmake based build system (preferred)
 +
make de-gnucash-guide-check
 +
</SyntaxHighlight> This will run the <code>xmllint</code> command above over the full directory structure. As an aside you can generate the documentation in other formats, like pdf or html by replacing ''check'' in the commands above with ''pdf'' or ''html'' respectively:<SyntaxHighlight lang="sh">
 +
# Run this for the autotools based build system (deprecated!)
 +
(cd guide/de && make pdf)
 +
# Or run this for the cmake based build system (preferred)
 +
make de-gnucash-guide-pdf
 +
</SyntaxHighlight>
 +
## In order to be able to see your work in yelp you still have to install it. From the build directory run:<SyntaxHighlight lang="sh">
 +
make install
 +
</SyntaxHighlight>
 +
## To see your work in yelp use the following command<SyntaxHighlight lang="sh">
 +
# In the command below, replace
 +
# <language> with the language of the doc you want to view, for example C (for English), de (for German),...
 +
# /path/to/gnucash-docs with the real path to the source directory for your documentation
 +
# <docname> with the document you wish to view, either gnucash-help or gnucash-guide
 +
LANG=<language> XDG_DATA_DIRS=/path/to/gnucash-docs/install/share:${XDG_DATA_DIRS}:/usr/local/share:/usr/share yelp gnome-help:<docname>
 +
# Example:
 +
LANG=pt XDG_DATA_DIRS=/path/to/gnucash-docs/install/share:${XDG_DATA_DIRS}:/usr/local/share:/usr/share yelp gnome-help:gnucash-guide
 +
</SyntaxHighlight>This uses yelp's built-in mechanism to select the proper language.
 +
## Alternatively you can open the installed document directly via:<SyntaxHighlight lang="sh">
 +
yelp /path/to/gnucash-docs/install/share/gnome/help/<docname>/<language>/<docname>.xml
 +
</SyntaxHighlight>You need to make the same replacements as in the other form.
 +
## Repeat these steps until you're satisfied with the result.
 +
# Update the branches of your local repo often:
 +
#:<code> git checkout maint              # switch to maint</code>
 +
#:<code> git pull --rebase              # update it</code>
 +
#:<code> git rebase maint working-branch # update working-branch</code>
 +
#:<code> git checkout working-branch    # switch back to working-branch</code>
 +
# Follow [[#Submitting your work direct to GnuCash]].
  
To translate the help files, repeat steps 2-6 but replace the "guide"
+
To translate the help files, repeat steps 2-10 but replace the "guide"
 
directory with "help".
 
directory with "help".
 +
 +
'''Committers:''' If it builds fine, add the directory changes from 2. also to <tt>gnucash/maint/packaging/win32/install-impl.sh</tt> and merge the change to master, if required.
  
 
=== DocBook xml editors ===
 
=== 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 . Some developers use [[Eclipse]].
+
For editing these DocBook xml files, various editors can be used: {{URL:wp}}DocBook might contain pointers to some, or also https://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html.
 +
:Some developers use [[Eclipse]].
 +
:The [https://de.wikipedia.org/wiki/OmegaT german wikipedia] says the translation tool [https://omegat.org/ OmegaT] can work on docbook.
  
 
People have said that AbiWord and OpenOffice / LibreOffice have support for DocBook available, in which case you could directly edit gnucash's xml files with those. However, those editors will probably not work with the current multi-file setup where each chapter is in a separate XML file and the main XML file contains points to the chapters' files. As a workaround, you can copy the relevant parts of the main XML file into the chapter's file by a plain text editor so that it "looks like" one single DocBook document. This can be opened with OpenOffice/LibreOffice and edited as normal. After that, the added parts from the main file need to be removed again, and then you have the edited chapter text.
 
People have said that AbiWord and OpenOffice / LibreOffice have support for DocBook available, in which case you could directly edit gnucash's xml files with those. However, those editors will probably not work with the current multi-file setup where each chapter is in a separate XML file and the main XML file contains points to the chapters' files. As a workaround, you can copy the relevant parts of the main XML file into the chapter's file by a plain text editor so that it "looks like" one single DocBook document. This can be opened with OpenOffice/LibreOffice and edited as normal. After that, the added parts from the main file need to be removed again, and then you have the edited chapter text.
Line 661: Line 1,206:
  
 
Some translators are more familiar with using po file editors like poedit, Kbabel, Gtranslator etc. For those people, it is possible to convert the content of the help documents (the DocBook XML files) into po files, translate the messages in the po file, and convert the result back into xml. This section describes how to use this approach for the gnucash help documents.
 
Some translators are more familiar with using po file editors like poedit, Kbabel, Gtranslator etc. For those people, it is possible to convert the content of the help documents (the DocBook XML files) into po files, translate the messages in the po file, and convert the result back into xml. This section describes how to use this approach for the gnucash help documents.
 +
 +
;The downside of this approach: It will be much harder for the documenters to fix e.g. broken links in times where you are inactive.
  
 
In order to use po files you have first to convert xml files to po files, translate them and then convert back to xml.
 
In order to use po files you have first to convert xml files to po files, translate them and then convert back to xml.
Line 667: Line 1,214:
 
  <code> yum install gnome-doc-utils</code>.
 
  <code> yum install gnome-doc-utils</code>.
  
#Do the convertion with the following commands (xx is your language code, example: el for Greek):  
+
#Do the conversion with the following commands (xx is your language code, example: el for Greek):  
 
#: <code>xml2po -o helpfile.xml.pot helpfile.xml</code>
 
#: <code>xml2po -o helpfile.xml.pot helpfile.xml</code>
 
#: <code>mv helpfile.xml.pot helpfile.xml.xx.po</code>
 
#: <code>mv helpfile.xml.pot helpfile.xml.xx.po</code>
Line 688: Line 1,235:
 
and set a bookmark in browser to the index.html so that you get the docs
 
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
 
any time you need them. The context sensitive facility is lost, but for
general reading it works.[https://lists.gnucash.org/pipermail/gnucash-user/2008-September/026699.html]
+
general reading it works.[{{ListURL}}/pipermail/gnucash-user/2008-September/026699.html]
 +
 
 +
=== GnuCash Maintainer Tasks ===
 +
For new languages the core developers have some additional tasks:
 +
 
 +
==== New Script ====
 +
Check <code>make pdf</code>! Do we need additional TTFs?
 +
 
 +
==== First Nightly ====
 +
Ask the admin of {{BuildServer}} to create the new directory.
 +
 
 +
==== First Release ====
 +
Adjust htdocs ...
  
 
== How to translate the files containing the new account hierarchies==
 
== How to translate the files containing the new account hierarchies==
Line 698: Line 1,257:
 
: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.  
 
: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.
+
: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 region 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.
 
: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.
Line 707: Line 1,266:
  
 
=== Prerequisite ===
 
=== Prerequisite ===
* If not done before, [[#Get the source from SVN]].
+
* If not done before, [[#Get the source from Git]].
  
 
=== Initialize accounts/<locale> ===
 
=== Initialize accounts/<locale> ===
 
* If it does not already exists, execute the following steps to initialize your <tt>accounts/<locale></tt> directory:
 
* If it does not already exists, execute the following steps to initialize your <tt>accounts/<locale></tt> directory:
# Create a new directory <tt>accounts/<locale></tt>.
+
# Copy the directory <tt>accounts/C</tt> to <tt>accounts/<locale></tt>
# Copy the <tt>acctchrt_*</tt> files from <tt>accounts/C</tt> to <tt>accounts/<locale></tt>
+
# In the directory <tt>accounts/</tt> change the file CMakeLists.txt and add your <locale> to both alphabetical sorted lists:
# Do not change any xml tags.  
+
## <syntaxhighlight lang="CMake">
# In the directory <tt>accounts/</tt>, change the file Makefile.am and add your <locale> to the only line in that file.
+
add_subdirectory(C)
 +
:
 +
add_subdirectory(<locale>)
 +
:</syntaxhighlight>
 +
## <syntaxhighlight lang="CMake">set(accounts_DIST ${C_DIST} ...  ${<locale>_DIST} ... ${dist_list} PARENT_SCOPE)</syntaxhighlight>
 +
# In <tt>accounts/<locale>/CMakeLists.txt</tt> adjust the <locale>:<syntaxhighlight lang="CMake">
 +
:
 +
set_dist_list(<locale>_DIST ${dist_account_DATA} CMakeLists.txt)
 +
 
 +
install(FILES ${dist_account_DATA} DESTINATION ${ACCOUNTS_INSTALL_DIR}/<locale>)
 +
file(COPY ${dist_account_DATA} DESTINATION ${ACCOUNTS_BUILD_DIR}/<locale>)
 +
</syntaxhighlight>
 +
#;Note: The next 2 steps are are discussed in [[#Localize the Account Charts]] below.
 +
# Localize <tt>acctchrt_full.gnucash-xea</tt>. This is only a helper file where you have all accounts in their context.
 +
# Now create the real modules by merging the respective parts from <tt>acctchrt_full.gnucash-xe</tt> in the other acctchrt_*.gnucash-xea files.
 +
* If you remove or create new files, adjust in <tt>accounts/<locale>/CMakeLists.txt</tt> the list<syntaxhighlight lang="CMake">
 +
set(dist_account_DATA
 +
  ...)
 +
</syntaxhighlight>
 +
* Whenever you changed one or more <tt>CMakeLists.txt</tt> files, you have to rerun <syntaxhighlight lang="sh">
 +
cd ${SOURCEDIR}
 +
cmake <your options>
 +
cd ${BUILDDIR} # e.g. .build
 +
make # or ninja</syntaxhighlight>
  
 
=== Localize the Account Charts ===
 
=== Localize the Account Charts ===
 +
'''Tip:''' <tt>C/acctchrt_full.gnucash-xea</tt> is a helper file. Because we prefer modularization it usually is not part of the distribution. It contains the full tree of the ''personal en_US accounts''. The other <tt>acctchrt_*.gnucash-xea</tt> files contain single branches of that. So after translating it you can copy&paste the respective parts in the other files to ensure consistency between them.
 +
 +
If you modularize the templates you should start with <tt>acctchrt_common.gnucash-xea</tt> - it is the most basic.
 +
 
For each ''desired'' <tt>acctchrt_*</tt> file in that directory:
 
For each ''desired'' <tt>acctchrt_*</tt> file in that directory:
# 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.
+
# Change the <tt>gnc-act:title</tt>, <tt>gnc-act:short-description</tt>, and <tt>gnc-act:long-description</tt> 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.
+
# For each <tt>gnc:account</tt> in the file
 +
## translate the <tt>act:name</tt>, and <tt>act:description</tt> fields.
 +
## Optionally you can
 +
### assign an '''account number''' <tt><act:code>1234</act:code></tt> after <tt><act:commodity-scu></tt> or
 +
### add a '''note''' as i.e. in <syntaxhighlight lang="xml" highlight="6-9">  <act:slots>
 +
    <slot>
 +
      <slot:key>hidden</slot:key>
 +
      <slot:value type="string">true</slot:value>
 +
    </slot>
 +
    <slot>
 +
      <slot:key>notes</slot:key>
 +
      <slot:value type="string">Some additional text about the usage of this account</slot:value>
 +
    </slot>
 +
    <slot>
 +
      <slot:key>placeholder</slot:key>
 +
      <slot:value type="string">true</slot:value>
 +
    </slot>
 +
  </act:slots>
 +
</syntaxhighlight>
 +
#: Please do ''not translate'' any other fields or the internally used ROOT account.
 
# To avoid typos, run the [[AccountHierarchyTemplate#Syntax Check]].
 
# To avoid typos, run the [[AccountHierarchyTemplate#Syntax Check]].
 +
# New files to be shown to the user must be added to the <tt>account_DATA</tt> section,
 +
#:helper files like ''acctchrt_full.gnucash-xea'' to <tt>EXTRA_DIST</tt> in <tt>Makefile.am</tt>.
  
 
'''Note again:''' You absolutely don't need to translate all of the files from
 
'''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
+
<tt>accounts/C</tt>.  A subset of those are fine as well. Probably several of
 
them will not apply to your local legislative/economic system anyway.
 
them will not apply to your local legislative/economic system anyway.
 
For a really customized account hierarchy you might better create a
 
For a really customized account hierarchy you might better create a
Line 730: Line 1,337:
 
tags from the accounts/C/acctchrt_* files.
 
tags from the accounts/C/acctchrt_* files.
  
If you wish to add new accounts, you will need some additional guids, those funny random numbers. To get them you can use:
+
If you wish to add '''new accounts''' manually, you will need some additional ''guids'', those funny random numbers. To get them you can use:
gnucash-make-guids
+
<SyntaxHighlight lang="sh">uuidgen | sed -e 's/-//g'</SyntaxHighlight>
or, if that command does not exist,
+
or use an online uuid generator like [https://www.guidgenerator.com/ this one] (any other one will do as well). Be sure to untick "Hyphens" to generate gnucash compatible guids. If you forget or the site you use doesn't offer that option, simply remove the hyphens yourself.
uuidgen | sed -e 's/-//g'
+
;Dependencies:''uuidgen'' is in a package ''''util-linux'''', '''sed''' has its own package. <!-- on opensuse; add different names for other distris -->
  
[[AccountHierarchyTemplate]] describes, how to create new templates e.g. for business purpose according local rules.
+
[[Account Hierarchy Template]] describes, how to create new templates e.g. for business purpose according local rules.
  
 
=== Test your Work ===
 
=== Test your Work ===
Line 742: Line 1,349:
 
* If you removed accountcharts, remove their line from <tt>account_DATA</tt>,
 
* If you removed accountcharts, remove their line from <tt>account_DATA</tt>,
 
* if you added new files, insert lines with their names and "\" (the line continuation symbol).
 
* if you added new files, insert lines with their names and "\" (the line continuation symbol).
 +
 +
== How to create localized Income Tax Tables ==
 +
;Note: This section is under developement and mostly untested!
 +
 +
As of the beginning of 2015 there is an nice US tax module with a report and export in TXF format.
 +
Additional there is a small de_DE derivate for the monthly VAT declaration. you can compare them to see, how you can tweak them to get something else.
 +
 +
=== Tax Table ===
 +
From https://github.com/Gnucash/gnucash/blob/maint/src/tax/us get the files
 +
* txf.scm - the tables, and
 +
* txf-help.scm - the descriptive help strings for each TXF code. This is also used to get a table in gnucash-docs/help/
 +
 +
They have relative simple table structures:
 +
(define txf-tax-entity-types
 +
contains a list of forms for different entities (person, company,...).
 +
(define txf-income-categories ...
 +
(define txf-expense-categories ...
 +
contain for each of the above lists the entries. If you compare this file with the respective *_DE file, you can see an example localization with additional categories:
 +
(define txf-asset-categories ...
 +
(define txf-liab-eq-categories ...
 +
It should be possible to adapt the lists for your tax forms. Then you might submit them to an enhancement request in buzilla, product:Gnucash, component:TXF Export.
 +
 +
=== Report and Export===
 +
Probably you need to have other export reports. That are in
 +
https://github.com/Gnucash/gnucash/tree/maint/src/report/locale-specific/us like
 +
* txf-export.scm
 +
* us.scm is unused
 +
Here you might probably need some help from a programmer.
  
 
== How to translate the website ==
 
== How to translate the website ==
* Get a checkout of http://svn.gnucash.org/repo/htdocs/trunk
+
:;Note about OS: 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[-w64]), but that's untested so far. Please report your findings here.
* Run the command <pre>make pot</pre>
+
 
 +
* Get a checkout of https://github.com/Gnucash/gnucash-htdocs
 +
* Run the command <syntaxhighlight lang="sh">make pot</syntaxhighlight>
 
* Then depending on whether or not a translation for you language exists already (complete or not):
 
* Then depending on whether or not a translation for you language exists already (complete or not):
*# Existing translation:<br>Run the command <pre>msgmerge po/LL.po po/gnucash-htdocs.pot -o po/LL.po</pre>Where LL is your language code, see earlier sections
+
*;Existing translation:<br>Run the command <Syntaxhighlight lang="sh">
*# New translation:<br>Copy the newly created file po/gnucash-htdocs.pot to po/LL.po, where LL is your language code, see earlier sections
+
msgmerge --previous -U po/LL.po po/gnucash-htdocs.pot
* Translate the po file as usual
+
</syntaxhighlight> where LL is your language code, see [[#Naming Convention]] above.
* Optionally run <pre>recode -d <input_encoding>..h0 po/LL.po</pre> to get special characters HTML quoted.
+
*:;Alternative: <syntaxhighlight lang="sh">make msgmerge</syntaxhighlight> will update ''all'' .po files
* 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.
+
*;New translation:<br> In the po directory run
 +
*:;As translator: <syntaxhighlight lang=sh>msginit</syntaxhighlight> This will insert your name, email and locale settings into the new file. If that fails copy the newly created file po/gnucash-htdocs.pot to po/LL.po, where LL is your language code, see [[#Build a new .po file]] earlier.
 +
*:;As maintainer: <syntaxhighlight lang=sh># Set LL=<language code>
 +
msginit --no-translator --locale=$LL</syntaxhighlight> This will create  a new file $LL.po without personal data. Continue with [[#Maintainers Task]].
 +
* Translate the po/LL.po file as described in [[#Translating the .po file]].
 +
*;Priority:
 +
::;High: Startpage: {index|externals/*}.phtml
 +
::;Low: sizing.phtml (outdated) search/templates/NMZ.* (unused)
 +
::;Medium: the rest depends on you.
 +
* Run <syntaxhighlight lang="sh">msgfmt -c --statistics po/LL.po</syntaxhighlight> to see your success.
 +
* Optionally run <Syntaxhighlight lang="sh">recode -d <input_encoding>..h0 po/LL.po</Syntaxhighlight> to get special characters HTML quoted.
 +
* Send your LL.po either as
 +
** GitHub Pull Request or
 +
** attachment of a Bugzilla enhancement request to the mainteiner team.
  
<ul>Note:</ul> 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.
+
===Maintainers Task===
 +
For '''new languages''' adjust the appropriate
 +
:* <syntaxhighlight lang="sh">git add po/LL.po</syntaxhighlight>
 +
:* <tt>Makefile</tt>,
 +
:* <tt>lang.php</tt>,
 +
:* <tt>externals/header.phtml</tt> rules,
 +
:* copy the directory <tt>news/en</tt> to <tt>news/<ll></tt> and
 +
:* create <tt>locale/<ll></tt>.
 +
 
 +
To make the changes visible, you will have to  
 +
* run
 +
msgfmt -c --statistics po/<ll>.po -o locale/<ll>/LC_MESSAGES/gnucash-htdocs.mo
 +
: or to compile ''all'' translations
 +
make mos
 +
* and include the mo file(s) in your commit.
  
 
== Tips for Developers ==
 
== Tips for Developers ==
 +
This section moved to [[I18N]].
  
This section collects some notes for developers/programmers on how to correctly prepare their code for translations.
+
==Project Maintainers==
 +
Some notes for Maintainers:
 +
===When to msgmerge===
 +
Some translators complain, it is so hard to update .po files. When should we do it?
 +
;From https://translationproject.org/html/robot.html: The Translation Project robot is not allowed to update the registry with new information about maintainers, languages, or translators, nor is it allowed to process POT files. These things are still handled by hand. ''When a new POT file is being registered by a project coordinator, the registering script calls <tt>msgmerge</tt>'' when previous translations exist, so translators are notified of a PO file which is up-to-date. New POT files are announced automatically to a team's mailing list, if the team has asked for this feature.
 +
So for $TP_LINGUAS it is done on each release. Probably we should do it, too?
  
=== How to make strings in code translatable ===
+
===Merging with divergent source trees===
 +
The source tree in GnuCash 2.7 was thoroughly restructured, so it is now very different from 2.6. One side effect of this is that the MsgIds in our 2.7 *.po files are in a completely different order compared to 2.6. This means <code>git merge</code> of maint in unstable will break the 2.7 *.po files. So when merging from 2.6 to 2.7 we have to ignore all changes in the maint po files at this point.
 +
To rescue at least parts of the work, try this.
 +
<syntaxhighlight lang="sh">
 +
# Set your language in LL, e.g.: export LL=de
 +
# while you are in the maint branch save your .po file outside of the repo e.g. as maint."$LL".po
 +
git checkout unstable
 +
git merge maint                                      # resolve the full LL.po merge by using the unstable version of LL.po (other files can be merged as normal)
 +
cd ../build                                          # assuming ../build is your build directory
 +
make pot                                              # update the template with changes from maint
 +
cd ../src/po                                          # assuming src is your gnucash git repo
 +
msgmerge "$LL".po ../build/po/gnucash.pot -o "$LL".po # update the po of your $LL
 +
msgcat --use-first "$LL".po ../<path_to>/maint."$LL".po -o "$LL".new.po
 +
</syntaxhighlight>
 +
For the best result you might test different msgcat parameters. Finally
 +
<syntaxhighlight lang="sh">mv "$LL".new.po "$LL".po</syntaxhighlight>
  
Strings in Glade files are marked for translations by the <tt>(_ )</tt> functions.
+
== Background ==
 +
This section was started to get some overview, '''work in progress!'''
 +
Beyond it helped to get rid of the outdated [[#IntlTool]] in version 2.7.6.
 +
For details see the [{{URL:Gnu}}software/gettext/manual/gettext.html GetText Manual].
  
Normally, strings in C code just need to be enclosed with the <tt>_( )</tt> function (well, actually it is a macro expanding into a function, but this is usually just an implementation detail). For example,
+
=== Packages ===
func("A translatable string!");
+
In our build process we use beneath self written scripts the following packages:
should instead be written as
+
* glib2-devel: glib-gettextize     
func(_("A translatable string!"));
+
* gettext, probably broken in:
 +
** -runtime: msgfmt, ...
 +
** -tools: (autopoint), gettextize, msg*, xgettext, ...
 +
** -runtime-tools-doc: manuals etc.
 +
* (only up to 2.7.5) intltool: Intltool*
  
However, it is important to keep in mind that <tt>_( )</tt> is a function; this means that in certain situations it cannot be used. For example,
+
=== Our Build Process ===
gchar* array_of_strings[] = {_("first string"), _("second string"), _("third string")};
+
This was the old (upto 2.6) autotools build process, which went through the following scripts:
would cause a compiler error. Instead, these strings should be wrapped with the <tt>N_( )</tt> macro, which is declared as <code>#define N_(String) gettext_noop(String)</code>. Then, whenever one of the strings is actually ''used'' (as opposed to ''declared''), it should be wrapped with the <tt>_( )</tt> function again:
+
gchar* array_of_strings[] = {N_("first string"), N_("second string"), N_("third string")};
+
====== autogen.sh ======
func(_(array_of_strings[0]));
+
;Note: Autotools were only used up to 2.6 branch. 2.7 and later use [[CMake]] instead.
 +
;glib-gettextize: helps to prepare a source package for being internationalized through gettext. It is a ''variant of the gettextize'' that ships with gettext.
 +
:glib-gettextize differs from gettextize in that it doesn't create an intl/ subdirectory and doesn't modify po/ChangeLog (note that newer versions of gettextize behave like this when called with the --no-changelog option).
  
See also: [[Translation#Disambiguation_prefix | Disambiguation prefix]]
+
»Note that on GNU systems, you ''don't need to link with libintl'' because the '''gettext library functions are already contained in GNU libc'''.« (glibc) [{{URL:Gnu}}software/gettext/manual/gettext.html#Overview]
  
==== Plural Forms ====
+
====== configure.ac ======
 +
* Sets
 +
ALL_LINGUAS= ...
 +
In recent versions it can be substituted by LINGUAS files in the po directories. We should consider this to distinguish TP vs. GC maintained translations.
 +
GETTEXT_PACKAGE=gnucash
 +
This is intltool style. Gettext uses PACKAGE=...
 +
AC_SUBST(GETTEXT_PACKAGE)
 +
AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, "$GETTEXT_PACKAGE",
 +
    [GetText version number])
  
Not all languages have the same simple kind of plural forms as english. See [http://www.gnu.org/s/hello/manual/gettext/Plural-forms.html gettexts Plural-forms] for details.
+
AM_GNU_GETTEXT_REQUIRE_VERSION|AM_GNU_GETTEXT_VERSION(x.yy.zz) can be used to require a version. We should use it to avoid ...
 +
* TP expects > 0.11.
 +
* gnulib expects >= 0.17
 +
* RHEL7 offers 0.18.2 (RHEL6 0.17)
 +
* Debian Stable offers 0.18.1 and in backport 0.19.3
 +
* '''Glade2 msgctxt''' and Glade3 were implemented in 0.18.3 - July 2013
 +
* '''GSettings''' and '''Desktop''' entries are implemented in 0.19 - June 2014
 +
* and got bugfixes until Version 0.19.3 - October 2014
 +
* '''Scheme''' format strings got a fix in 0.19.4 - December 2014
 +
* '''AppData''' support: [https://lists.gnu.org/archive/html/info-gnu/2015-09/msg00003.html gettext-0.19.6 released] - 2015-09
 +
* ? custom XML formats in 0.19.7
 +
:<gjanssens> GtkUIManager files don't contain translatable strings as far as I know. They're not in POTFIILES.in either.
 +
* at the time of our last update: [https://lists.gnu.org/archive/html/info-gnu/2016-06/msg00006.html gettext-0.19.8.1 released] - 2016-06
 +
* [{{BugURL}}/show_bug.cgi?id=725296#c21 gjanssens sv->swedish patch for Windows] is in gettext 0.20. It is also the first version , which extracts <developer_name> from appdata.xml. [{{ListURL}}/logs/2020/01/15.html#T15:20:46 IRC log]
 +
* recent: [https://lists.gnu.org/archive/html/info-gnu/2019-05/msg00011.html GNU gettext 0.20.1 released] - May 12, 2019
  
=== How to give the translators a clue ===
+
This setting then can be used by autoPoInt. Watch the caveaets from https://www.gnu.org/software/gnulib/manual/html_node/gettextize-and-autopoint.html:
 +
: On the other hand, if your package is not as concerned with compliance to the latest standards, but instead favors development on stable environments, the steps are:
 +
:# Determine the oldest version of gettext that you intend to support during development (at this time, gnulib recommends going no older than version 0.17). Run autopoint (not gettextize) to copy infrastructure into place (newer versions of gettext will install the older infrastructure that you requested).
 +
:# Invoke gnulib-tool, and import the gettext-h module. # Fixme: Meaning?
  
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.
+
:Regardless of which approach you used to get the infrastructure in place, the following steps must then be used to preserve that infrastructure (gnulib’s bootstrap script follows these rules):
 +
:# When a script of yours run autopoint, invoke gnulib-tool afterwards.
 +
:# When you invoke autoreconf after gnulib-tool, make sure to not invoke autopoint a second time, by setting the AUTOPOINT environment variable, like this:
 +
::<pre>$ env AUTOPOINT=true autoreconf --install</pre>
  
Example: <pre>
+
AM_GLIB_GNU_GETTEXT          # FIXME: Meaning?
/* Translators: the following string deals about:
+
*runs checks with settings
  * The Answer to Life, the Universe and Everything
+
** AC_PROG_INTLTOOL
  *
+
** AC_CHECK_HEADERS(ltdl.h, ...
  * http://en.wikipedia.org/wiki/Phrases_from_The_Hitchhiker%27s_Guide_to_the_Galaxy */
+
dnl Make sure we have a proper gettext installed
  func(_("42")); </pre>
+
AC_MSG_CHECKING(for a valid gettext/gmsgfmt installation)
 
+
  if test "$gt_cv_have_gettext" != "yes" || test "x$GMSGFMT" = "x"; then
In the pot and po files, this comment will show up as follows:
+
  AC_MSG_RESULT(no)
<pre>
+
  AC_MSG_ERROR([Cannot find Glib Gettext. Maybe you need to install the gettext package?])
# foo/bar.c:123
+
else
# Translators: the following string deals about:
+
  AC_MSG_RESULT(yes - $GMSGFMT)
# The Answer to Life, the Universe and Everything
+
fi
#
 
# http://en.wikipedia.org/wiki/Phrases_from_The_Hitchhiker%27s_Guide_to_the_Galaxy
 
msgid "42"
 
msgstr "" </pre>
 
  
While this feature seems to work fine in C sources, it seems not to work in the scm files. Any suggestions, to fix this are welcome.
+
====== makefile.am ======
 +
has the following section:
 +
.PHONY: pot
 +
pot: Makefile po/POTFILES.in
 +
rm -f po/$(PACKAGE).pot
 +
${MAKE} -C po $(PACKAGE).pot
 +
 +
 +
$(srcdir)/po/POTFILES.in: make-gnucash-potfiles .potfiles
 +
if test -w $(srcdir)/po/POTFILES.in ; then ./'''make-gnucash-potfiles''' > $(srcdir)/po/POTFILES.in ; fi
 +
 +
# Creation rules so that po/gnucash.pot can always be created for
 +
# make dist.
 +
po/gnucash.pot: po/POTFILES.in
 +
${MAKE} -C po gnucash.pot
 +
 +
.potfiles:
  
=== Further Reading ===
+
====== make-gnucash-potfile.in ======
 +
This is a self written perl script from the time as gettext had several issues. It creates '''po/potfiles.in''', the "list of files which contain translatable strings". This script is not used in a cmake based build environment for gnucash. As gnucash 2.7.4 and more recent is cmake only, this file has been removed starting from that release.
  
If you want to read more about this topic, [http://live.gnome.org/GnomeI18nDeveloperTips GnomeI18nDeveloperTips] might be a good starting point.
+
====== xgettext ======
  
 +
;xgettext: Extract translatable strings from given input files. See --language for supported list:
 +
:;--language=NAME: recognise the specified language ('''C''', '''C++''', ObjectiveC, PO, Shell, ''Python'', Lisp, EmacsLisp, librep, '''Scheme''', Smalltalk, Java, JavaProperties, C#, awk, YCP, Tcl, ''Perl'', PHP, GCC-source, NXStringTable, RST, '''Glade''', Lua, JavaScript, Vala, '''Desktop''')
 +
:Options, which we should check:
 +
:;--copyright-holder=STRING: set copyright holder in output
 +
:;--foreign-user: omit FSF copyright in output for foreign user
 +
:;--msgid-bugs-address=EMAIL@ADDRESS: set report address for msgid bugs
  
 
----------------------------------------------------------------------
 
----------------------------------------------------------------------
 
Thanks so very much to all the translators for their hard effort and
 
excellent work.
 
  
 
[[Category:Translation]]
 
[[Category:Translation]]

Revision as of 12:13, 9 February 2021

Tip
Use Google translation and select your language to get a translation of this document.

The concept of this document is to give you step-by-step instructions on how to create or update translations and other localization tasks for the gnucash project. See Translation Status for the current status of the project with respect to translation contributions.

Contents

Overview

GnuCash has several separate areas that need translations or localization, which are by priority:

  • A glossary file: A reference in form of a message catalog with roughly 200 terms that are commonly used throughout GnuCash and their explanation. Preferably it should be translated first for each new language to define a consistent terminology for the other parts.
  • The program's message catalogs: These contain all text messages for the application's user interface. It currently consists of roughly 5000 strings. Not all are equally important though.
The following languages are currently maintained at the #translationproject.org: [1]
  • A Windows Installer with about 20 strings.
  • The account templates: A set of ready to use account chart snippets for personal users that can be mixed and matched into a full chart of accounts during the creation of a new a new GnuCash file with currently 115 translatable account names.
  • If your government or other authorities offer specific templates for business users, you can create them, too.
  • The documentation: The Help Manual and the Tutorial and Concepts Guide. These documents explain how to use GnuCash. They are written in DocBook, an XML variant.
  • The website, while mostly written in PHP/HTML, uses message catalogs, too. Currently it has 430 messages.
    • In theory one could also translate recent announcements from the news directory into the language specific subfolder, but ususally there are more important tasks around.
  • Income Tax Tables require some knowledge of your regional tax rules and are related to account templates.
  • Optionally you can #Check Files in Repo gnucash's doc Directory files, too.

GnuCash uses the translation of the ISO 4217 currency codes and names. This are maintained by the ISO Codes Team. If your language is missing or has issues contact them.

Available resources

There are many resources to support you at gnucash.org and other places. Don't hesitate to use them.

gnucash.org

We have collected a bunch of useful information for you here in this wiki -

navigate from the main page or use the search function -

and on the website Template:WebURL.

And we have several channels of communication and a few other useful tools:

IRC

The fastest way to get help is using the internet relay chat IRC, as many of the developers hang out there and are eager to help.

Mailing lists

Translators will probably find two or three gnucash mailing lists of interest. If you can not find the answers to your questions in their Mailing_Lists#Mailing List Archives, feel free to ask them.

  • For language and region specific questions, where you should discuss terms and ask for proofreading of your work, use your languages mailing list. Currently we have
    gnucash-[pt_]br, de, es, fr, it, nl.
If none exists for your language or nobody has an answer there, use the english lists:
  • General use questions and answers are found on the gnucash-users mailing list,
  • specific development questions go to the gnucash-devel list.
  • If you dislike the heavy traffic on the above lists, you should at least subscribe the gnucash-announce list to get informed about new releases.

To subscribe or view archives of these lists follow the links to the Mailing Lists.

translationproject.org

The Translation Project coordinates the message cataloges of several programs; you can see which languages they host on their GnuCash page and learn about their process here.

If you want to help with an existing Translation Project translation or add a new translation under their aegis, please contact the language team using the information on their team page.

Coordinating Message Catalog Translations

New Message Catalogs

The Translation Project requires that you use either an existing translation or gnucash.pot from the latest release as the basis for your translation.

Updating Message Catalogs

Usually you will use your po file from their site, but sometimes we apply global changes like removing the trailing colon from GUI labels. In that case you can save time by merging such updates from our version.

Coordinating Account Templates and Documentation

The Translation Project handles only message catalogs, so if you have glossaries, account templates or documentation translations you'll submit them directly to us.

Direct Contribution

If you want to work on a translation that's not coordinated by the Translation Project or a new translation and you want to submit it directly to GnuCash, read on. If it's an existing translation please try to contact the last translator first using the contact information in the message catalog.

If you're starting a new translation it's much easier to begin with a tarball, which will include po/gnucash.pot; if you start from a Git clone you'll have to build Gnucash yourself first to generate gnucash.pot.

On Other Sites

General Translations Guidelines and Tips

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

Other Web Based Translation Tools

Several services for translation coordination exist, see Improve Localization Process#Web Based Translation Tools. As we have no experience with them contact the gnucash-devel mailing list before using them.

Weblate

Since 2020-12-14 we are experimenting on GnuCash @ Hosted Weblate.

Other Useful Sites

  • There are many online dictionaries, use a search engine like google, to find the best fitting.
  • An index of on-line dictionaries and a lot of other resources can be found at www.yourdictionary.com.
  • 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.

How to submit changes directly to GnuCash

Once you've got a translation ready for submission, there are three options:

Pull Requests at GitHub

If you already are a github user you can publish your work as a separate branch on your gnucash[-{[ht]docs|on-windows}] fork and send a pull request to the GnuCash team. If you wish to continue your work before the request was completed, simlply create a new working branch. After the pull request was completed you can delete the related branch again. See Git for details.

Commit messages
Start your commit message with L10N:<LL>: were <LL> - or ${LL} below - is your language code.
If applicable, add a with the output of msgfmt -c --statistics ${LL}.po.
Also the POT-Creation-Date might be of interest to see how recent the translation is.
Example
L10N:de: 5423 übersetzte Meldungen.

Patches at Bugzilla

The easiest is to use Bugzilla:

containing the diff between the old files - if any - and your new files:
  • If you have Git installed, the easiest way to create the patch is git format-patch origin/maint..maint.
  • Else you can use diffutils: diff -u[r] <original path> <modified path> > <name>.patch. See info diff for details.

Mailing lists

You can simply email your completed message catalog (.po file) to the developers at the gnucash-devel mailing list. We'd really rather you use Bugzilla or Github because those are much less likely to get lost or forgotten, but if you really find those too hard we'll try to accommodate you on the list.

Translating the Program

To begin a translation you need either the message template file (gnucash.pot) if you're starting a new translation or the existing message catalog (xx.po or xx_YY.po, where xx is the ISO code for your language and YY the ISO code for a language-variant locale, see Naming Convention). These files are in the gnucash sources, which you can obtain either from our git repository or by downloading the latest release tarball from Sourceforge.

Get the source from Git

GnuCash uses Git as a version control system. Click here for an introduction to Git.

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

Normally checkout the current stable branch:

git clone https://github.com/Gnucash/gnucash ${SOURCEDIR}
cd ${SOURCEDIR}
git checkout maint

The argument ${SOURCEDIR} above can be whatever you want your local directory to be called, and is optional in the first line. If you leave it out, you'll have a directory called gnucash created containing all the source code below your current working dir.

Checkout the documentation (optional, but recommended):

git clone https://github.com/Gnucash/gnucash-docs gnucash-docs
cd gnucash-docs
git checkout maint

Update your repository

After this initial git checkout, you can later update your local repository using

git pull --rebase

from anywhere in the tree of ${SOURCEDIR}. We recommend to do it daily when you start your work.

Get packages, which are used while building

  • Dependencies contains the list of packages, which are used while building GnuCash. If some are missing the configuration by cmake or the build by make or ninja will fail.
  • For working on .po files we use several commands starting with msg. This are part of gettext-tools.
Caution
Gettext versions < 0.20 are known not to extract the 'developer_name' xml node, which contains the msgid "GnuCash Project". Do not remove this msgid!

Under Linux use your package manager and install them.

Steps in the Build System

GnuCash uses the cmake build generator to control the build of all components. Details are described in Building. The following short-form instructions work on Unix systems and assume that you have already set up the dependencies according to the FAQ. If you are building the unstable or master branches you'll need to use your package manager to install two more development packages, boost-all-devel and googletest.

Configuration

It's generally preferred to use a separate build directory. For translators it's convenient to make this a hidden directory in the source directory as that provides the least complicated paths in the translation template; hiding the directory prevents the extraction tool from including build products in the files searched for translatable strings. We'll call the directory .build. You can call it anything you like, just remember to start the name with a dot so that it's hidden.

Change directories to your build directory and run cmake to configure the build. In most cases translators will not need to install GnuCash and it will build any arguments:
cd ${BUILDDIR} # e.g. .build
cmake ..

tells cmake to configure the current directory using the CMakeLists.txt in the parent directory. If configuration fails or if you want to refine your build consult Building.

Optional Compile

It is suggested that you compile the gnucash source code. 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.

make
Note
Advanced users might consider to use Ninja instead of Make, but that is behind the scope of this page.

Next, compile gnucash in the build directory:

cd ${BUILDDIR} # e.g. .build
make

GnuCash can be run from the build directory as follows:

cd ${BUILDDIR} # e.g. .build
GNC_UNINSTALLED=1 GNC_BUILDDIR=`pwd` bin/gnucash

It is a good idea to use absolute paths like this to insure you run the proper gnucash executable. To run your distributions pre-installed version of gnucash, under Linux 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. You can find details in Locale Settings.

Documentation

The GnuCash Help Manual and the Tutorial and Concepts Guide can either use the same CMake build system as the code or the older Autotools.

  • To make a browsable documentation set with Autotools:
    1. git clone gnucash-docs or unpack a gnucash-docs tarball
    2. create a hidden build directory just as you did for GnuCash itself
    3. run autogen.sh
      ./autogen.sh
      
    4. change directory into the build directory
      cd .build
      
    5. run the following commands
      ../configure
      make html
      
  • To make a browsable documentation set with CMake:
    1. git clone gnucash-docs or unpack a gnucash-docs tarball
    2. create a hidden build directory just as you did for GnuCash itself
    3. change directory into the build directory
      cd .build
      
    4. run the following commands
      cmake ..
      make html
      

The new documentation home pages will be

guide/<locale>/gnucash-guide/index.html and
help/<locale>/gnucash-help/help.html,

where <locale> is one of C, de, it, ja, or pt (English, German, Italian, Japanese, or Portuguese respectively). You can use the file: URL scheme to point your browser to one of them; the links will work from there.

Naming Convention

The language code is of the following form:

<language>[_<REGION>][.<Charset>][@modifier]
using the well known ISO codes 639-1 for languages and 3166-1 for regions, which are in most cases countries .
  • Only if no 2 letter code exists for your language in ISO_639-1, use the 3 letter code from ISO_639-2.
  • If you are the first translator for your language, you should
    • name your files and directories only with your language code.
    • set Language: in the header of your po file with the full (language and region) code, if significant.
So all people using your language despite of their region will benefit from your work.
  • If there are parts, which are specific for your region, e.g. business account templates respecting local law, then they should be in a <language>_<REGION> directory.
  • The common charset in gnucash is utf8.
  • In the rare case different scripts are used for the same language like kyrilic and latin add for the less used the modifier e.g. sr@latin.

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

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"
"Report-Msgid-Bugs-To: https://bugs.gnucash.org/enter_bug.cgi?"
"product=GnuCash&component=Translations\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"
"Language: pt_BR\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\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 or does not answer in reasonable time), you will become the maintainer and you should change the "Last-Translator" to your name and email address.

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 - and the explanation of a few very specific for GnuCash like the disambiguation between bill, invoice and voucher. It is recommended that you get this file translated first, and use it as a guide when translating the real .po file or the documentation. Please keep in mind that this file will never be visible to a user! The glossary file is only a tool for you, the translators! I repeat: The strings from the glossary file will never be user-visible, they are only used by you, the translator.

Todo
The current files have a very informal form. To make them more useful like conversion in tool specific glossary formats, we should replace
msgid "generic term: term"
by
msgctxt "generic term"
msgid "term"
  1. Go into the glossary directory:
    cd po/glossary/
    
  2. If your .po glossary file does not exist or is older than gnc-glossary.txt, create the template:
    ./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot
    
  3. Create or update your language's glossary file:
    • If your .po glossary file does not exist,
    1. use this gnc-glossary.pot file to create it with
      msginit # add -l<locale> if different from your settings
      
    2. Add your file into the set_dist_list(po_glossary_DIST ...) command in glossary/CMakeLists.txt
      set_dist_list(po_glossary_DIST CMakeLists.txt bg.po ca.po da.po de.po el.po es_NI-policy.txt es.po fr.po gnc-glossary.txt he.po
              hr.po hu.po it.po nb.po nl.po pl.po pt_BR.po pt.po ru.po rw.po sk.po sv.po txt-to-pot.sh vi.po zh_CN.po zh_TW.po)
      
      to get it in the tarball.
    3. After changing CMakeLists.txt you have to rerun
      cmake # add your options
      
    • If your .po glossary file exists, but is older than gnc-glossary.txt use the msgmerge program to update it:
      msgmerge --previous -U LL.po gnc-glossary.pot;
      
  4. Now open your language's glossary file and translate it completely.
  5. Don't forget to #Check syntax and statistics of your .po file.

Terms missing or inadequate in the glossary file

If you detect an important term which is missing or could be better explained,

  • create a pull request at github or
  • open a bug for Product:GnuCash, Component:Translation and add a patch
for the source file gnc-glossary.txt.
With the exception of the header the lines of this file are alphabetical sorted and have the form:
Msgid<TAB>Comment
Reminder
Does your editor enter <TAB>s or will it replace them with <Space>s?

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

  1. To generate a new gnc-glossary.pot:
    ./txt-to-pot.sh gnc-glossary.txt > gnc-glossary.pot
    
  2. run above msgmerge command for your LL.po,
  3. check and translate the new string in this updated glossary file.
  4. If successful, update all *.po files with:
    for i in *.po; do echo -n "$i:"; LANG=C msgmerge --previous -U $i gnc-glossary.pot ; done
    #old form: find *.po -exec /usr/bin/msgmerge --previous -U '{}' gnc-glossary.pot \;
    
Note
The last step can also be done by a maintainer.
LANG=C is only recommend for maintainers to get english error messages.

Get a fresh template

The Portable Object Template (.pot file) is a collection of all translatable strings.

It is important, to repeat this step e.g. after you asked a developer to change an insufficient string or you got an announcement about changed strings like commit messages starting with "I18N: " or containing a "[I18N]" flag.

Tip
If you have problems with this section, you download instead the "current template" from the translationproject.org. But keep in mind it is based on the last release and does not contain recent changes.
  1. If your repository is no fresh checkout, you should first #Update your repository:
    git pull --rebase
    
  2. Only on the first run see Building to set up your build environment depending on your OS.
    Note
    As you can use make or ninja, on this page we write always make <target>. If you decided to use ninja, execute ninja <target> instead.
  3. Then in gnucash, a specific command at the top-level of the build tree (or source tree, if you do not use a separate build directory) will perform all necessary steps for this:
    cd ${BUILDDIR} # adjust ${BUILDDIR}
    make pot
    
  4. If make complains make: *** No rule to make target `<path/to/missing-source-file>', needed by `gnucash.pot'. Stop. there are obsolete relicts from a previous build. Just run
    make clean  # remove obsolete files
    make pot    # try it again
    
  5. Now go into the po directory:
    cd ${SOURCEDIR}/po # adjust ${SOURCEDIR}
    

If your language file already exists, continue with #Update an existing .po file.

Build a new .po file

If there is no .po file for your language, then you can start a new one. Start by

msginit [-lLL[_RR]] [-i<path/to/>gnucash.pot]

where LL is your language and RR your region code, if there is already a different LL.po like e.g. pt and pt_BR.

-i<path/to/>gnucash.pot is required, if you use a separate build dir,
-l... is only required, if your target is different from your environments current language.

This will initialize the meta information with values from your user environment.

Note
msginit 0.19.3 is querying an obsolete address of the translation project for language teams, but that doesn't matter.

If that does not work you can copy the file gnucash.pot into a work file named LL.po and just edit this file.

Adjust the header and special messages

The top of the .po file should be edited somewhat. Most of this adjustments should already be done by msginit, but if you copied the template, you will have to adjust all.

  • 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.
    
Expand the copyright comment by a list of <Translator name> <email address>, year[ range] in reverse historical order. Then you can later copy the list into translator-credits.
  • This is also a good place to record typographic conventions, if more than one person work on the file:
    #
    # Konventionen/Tastenkürzel:
    # »Zitate«: [altgr]+[Y]/[X]
    # Gedankenstrich — [altgr]+[Shift]+[-]
    
  • The first, empty msgid "" contains information for you and the gettext tools. Each line of the msgstr contains a capitalized entry, a colon and a value. Replace all uppercase words with something appropriate. In this case, you will be the first author of the translation, and also the
  • Last-Translator: your name and email address. This person is responsible for the file, so we need an email address to contact you.
Do not change it, if you do not want to become the responsible person. Despite that you can add yourself to the above copyright section and translator-credits below.
  • Language-Team: Some languages are maintained by teams and everybody wants to get informed. That is the case for organizations like #translationproject.org or the german Gnucash translator team. Enter the teams name and email address. If you are no member of a team, keep it empty or write NONE. Team members can reuse this line in translator-credits
  • Language: should be the same as the filename without extension, usually the ISO code of your language.
  • Project-Id-Version: <Package name> and <Version>. Do not forget to update the version. msgmerge seems not to be able to do it for you.
  • Report-Msgid-Bugs-To: Should already been set by .msginit to https://bugs.gnucash.org/buglist.cgi?roduct=GnuCash&component=Translations or similar, where you can report issues with the msgids like
    • "There is a typo in <msgid>" or
    • "<msgid> is impossible to translate to <your language> because of the grammatical difference …"
  • POT-Creation-Date: gets updated by msgmerge.
  • PO-Revision-Date: The timestamp of the last modification. Editors with a specific po mode should update it on saving. If you use a normal text editor, you will have to do it manually.
  • Do not change the content section:
    "MIME-Version: 1.0\n"
    "Content-Type: text/plain; charset=UTF-8\n"
    "Content-Transfer-Encoding: 8bit\n"
    
    Older files can have an older form like:
    "CHARSET: UTF-8\n"
    "ENCODING: 8bit\n"
    
    . Replcae them with the recent form.
  • 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"
    
See Gettext Manual: Translating Plural Forms for details.
See the full explanation in Gettext Manual: Header Entry.
  • Remove the `#, fuzzy' line once you have specified the items in capitals, because once this is done the header entry is no longer fuzzy.
  • There is currently one special string:
    #: ../src/gnome-utils/gnc-main-window.c:4389
    msgid "translator-credits"
    msgstr ""
    "Joachim Wetzig, 2019\n"
    :
    "Jan-Uwe Finck, 1999\n"
    "\n"
    "Verbesserungsvorschläge zur Übersetzung an gnucash-de@gnucash.org"
    
This will appear in Help->About->Credits->Translation. So you should enter your name or that of your team and an email address where users can contact you for typos and gifts.
Tip
After some time more persons would have worked on the translation. Then you can expand it from your header comments to:
msgstr ""
"<current translator>, <years>\n"
"<previous translator>, <years>\n"
:
"<first translator>, <years>\n"
"\n"
"Send suggestions, critizism and questions about this translation to\n"
"Klingon speaking GnuCash community <gnucash-tlh@gnucash.org>\n."
"To avoid moderation we recommend to subscribe at\n"
"<a
# This comment exists only to trick the spamfilter. Rejoin the surrounding lines again.
 href=\"{{ListURL}}/mailman/listinfo/gnucash-tlh\">List gnucash-tlh</a>"
# Don't forget to replace Klingon (tlh) by your language and translate the rest!
If a list exists, we suggest to remove the email address of individuals for data protection reasons.

Prepopulate your file with translations from your glossary and other projects

The basic idea is decribed in Gettext Manual: Using Translation Compendia. Your translator tools might already support compendia. If not, i.e you are using a plain text editor, here is the manual way:

There are in total 3 programms in use:

msgcat
Concatenates and merges the specified PO files.
msgmerge
Merges two or more Uniforum style .po files together.
msgattrib
Filters the messages of a translation catalog according to their attributes or manipulates their attributes.
Example
To merge a compendiumn like our glossary:
cd ${SRCDIR}/po
# Gettext manual's suggestion to merge compendia without old po file:
msgmerge --compendium glossary/${LL}.po -o ${LL}.po /dev/null ${BUILDDIR}/po/gnucash.pot
# Perhaps better:
msgmerge -U ${LL}.po --compendium glossary/${LL}.po ${BUILDDIR}/po/gnucash.pot
GOffice

Gnucash has borrowed a couple of source files from goffice. Those files contain a number of translatable strings. The goffice translation teams have already put effort in translating those in many languages. To reduce our translation effort, the script linked in I18N#Borrowing Code can be used to import these translations into our own po files.

If the goffice part for your language is incomplete, you might consider to offer them to update their file with your work.

GTK3

Stock buttons became deprecated in their version 3.10. They included:

  1. a label with mnemonic,
  2. for which the translation was already done in the gtk domain,
  3. a unique icon was associated.

So they are no longer used since gnucash 3.0. We use still the same labels, but the GTK translation is not directly used.

You can save some work by merging the po file of your language from GTK3, i.e. from https://gitlab.gnome.org/GNOME/gtk/tree/gtk-3-24/po into your gnucash po file.

Example
To merge fitting translations from GOffice and GTK:
#Example to merge common parts from po files in GOffice and GTK

# Variant A: in single steps to watch their results
## 1. join 3. party translations
msgcat --use-first -o tmp.po ${LL}.po ${GOFFICEPATH}/po/${LL}.po ${GTKPATH}/po/${LL}.po
## 2. Remove unused messages. Authoritativ is gnucash.pot:
msgmerge tmp.po ${BUILDDIR}/po/gnucash.pot | msgattrib --no-obsolete > {$LL}.po
rm tmp.po

# Variant B: in one command:
msgcat --use-first ${LL}.po ${GOFFICEPATH}/po/${LL}.po ${GTKPATH}/po/${LL}.po | \
msgmerge ${BUILDDIR}/po/gnucash.pot | \
msgattrib --no-obsolete > {$LL}.po

Adjust po/CMakeLists.txt

Also include your language code into the NEW_LINGUAS variable in the CMakeLists.txt file in the po folder of your source directory:

# Set of available languages:
# * managed at the Translation Project (TP):
set (TP_LINGUAS az ca cs da eu fa ja nl rw sk sr sv tr uk zh_CN)
# * already marked as external at TP:
set (GC_LINGUAS ar bg de el en_GB es fi fr gu he hi hu it kn ko lt lv mr nb ne pl pt pt_BR ro ru ta te ur vi zh_TW)
# * New or unmarked: The release manager should announce them to TP 
# and when listed there move in the respective group above.
set (NEW_LINGUAS as brx doi es_NI kok kok@latin ks mai mni mni@bengali)

set (ALL_LINGUAS ${TP_LINGUAS} ${GC_LINGUAS} ${NEW_LINGUAS})

CMakeLists.txt is a file, which controls the configuration of the build process. So after changing it, you have to rerun cmake. Some IDEs like Eclipse will do it automagical for you.

As part of the build your LL.gmo file is generated in the po directory of your build tree. Finally make install will copy it to the place, where it will be found at runtime. If you forget one of the steps, your translated language will not appear.

Continue with #Translating the .po file.

Update an existing .po 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.

If your language file already exists, update it using the msgmerge program. This will move the old translations of unchanged strings in the new file:
msgmerge --previous -U LL.po gnucash.pot
Note
If you had choosen a separate build directory, e.g. .build, adjust the path in above command:
cd ${SRCDIR}/po # adjust ${SRCDDIR}
export BUILDDIR=../build # adjust this
msgmerge --previous -U LL.po ${BUILDDIR}/po/gnucash.pot
Note for maintainers
To update all .po files:
cd ${SRCDIR}/po # adjust ${SRCDDIR}
export BUILDDIR=../build # adjust this
for i in *.po; do echo -n "$i:"; msgmerge --previous -U $i ${BUILDDIR}/po/gnucash.pot; done
Separate commits for "noise" and real work
You should now run git commit or create a patch "L10N:<locale>: Merge recent template".
This will contain only the "noise" from the updated pot file as usually many line numbers change.
Diff example after msgmerge
 #. Business options
-#: ../src/app-utils/app-utils.scm:303
-#: ../src/business/business-gnome/gncmod-business-gnome.c:117
+#: ../src/app-utils/app-utils.scm:322
+#: ../src/business/business-gnome/gncmod-business-gnome.c:119
 msgid "Business"
 msgstr "Geschäft"
Hiding your real changes in hundreds of such sections will make it really hard for your coworkers to find them.

After having done your translation you submit a second commit or patch containing your actual work "Update <locale>.po".

You should also do it, if your current translation tool uses other format settings like line breaks as the previous tool. In this case just open the file, save it and git commit or create a patch "L10N:<locale>: Preparation: Reformating".

Example in KBabel format
#: ../src/app-utils/business-prefs.scm:33
msgid "The format string to use for generating customer numbers. This is a printf-style format string."
msgstr "Используемая строка форматирования для создания номеров клиентов. Её формат соответствует printf."
Example in PoEDit format
#: ../src/app-utils/business-prefs.scm:33
msgid ""
"The format string to use for generating customer numbers. This is a printf-"
"style format string."
msgstr ""
"Используемая строка форматирования для создания номеров клиентов. Её формат "
"соответствует printf."
Review the file header
  • Project-Id-Version should be GnuCash 5.5 and
<tt>POT-Creation-Date should be recent. If they are not, you probably forgot #Get a fresh template or #Updating an existing .po file.
  • The PO-Revision-Date should be >= POT-Creation-Date.

Some, but not all tools will do this reliably for you.

Translating the .po file

Finally. You are ready to do some translating!

The .po source files are plain text files.

Tools

Some plain text editors offer a specific syntax highlighting for .po files, but there are also specific tools you can use:

  • Emacs has the po-mode to edit po files.
  • Geany, an editor with sytax highlighting and a little bit more
  • 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. Update this, if you know it is fixed.
  • KBabel was another recommended tool, see Lokalize.
  • Lokalize is the successor of KBabel in KDE4.
  • Poedit to finish the PO file edit and build.
Version 2.1.1 had issues

(feel free to add more tools here)

Gettext source (.po) file format

Record Format

A record in a po file has the following form:

<empty or only white-space>
#  translator-comments
#. extracted-comments
#: reference…
#, flag…
#| msgctxt previous-message-context
#| msgid previous-untranslated-string
msgctxt optional-message-context
msgid untranslated-string
msgstr translated-string
  • The empty or only white-space line is the record separator.
  • In translator-comments you can put your own notes.
  • The extracted-comments are notes from the programmers for you.
  • One or more references tell you, where the message appears in the sources.
  • The most important flags will be explained below in # Common Flags and source language format flag will be explained below.
  • The previous-* entries will only appear, after msgmerge --previous … for fuzzy messages to show what changed.
  • An optional-message-context has the purpose to distinguish equal msgids with different meanings.
  • The msg* should explain themself above.
Example
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.

Common Flags
Fuzzy Flag

If you see a string that has the phrase #, fuzzy in the flags comment above it, review the translation and confirm it by removing

  • the , fuzzy flag, but no other flags like , c-format,
  • the #| msgid lines, and in some cases
  • the #| msgctxt line.

A fuzzy translation means that the translation will be ignored by the program.

There are at least 2 reasons for the fuzzy flag:

  1. one of the msg* programs took some guess about what the translation might be from similar msgids,
  2. in a previous version you had a valid translation, but a programmer changed (parts of) the msgid.
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. You can filter for fuzzy messages by running
cd ${SOURCEDIR}/po
msgattrib --fuzzy ${YOUR_LANGUAGE}.po
Example fuzzy message
#: messages-i18n.c:35
#, fuzzy, c-format
#| msgid "There was an error opening the file %s."
msgid "There was an error writing the file %s."
msgstr "Es gab einen Fehler beim Oeffnen der Datei %s."
Here the msgid was changed from "opening" to "writing". You need to correct the translated string, remove the line(s) with the old msgid "#| msgid …" and the 'fuzzy' flag, because only then the translation will actually appear in the program.
Example fuzzy fixed
#: messages-i18n.c:35
#, c-format
msgid "There was an error writing the file %s."
msgstr "Es gab einen Fehler beim Schreiben der Datei %s."
Notice that #, c-format was not removed. That is correct, you should leave that.
Format Flags

Because parts of GnuCash were written in different programming languages, there appear at least 2 different format flags:

c-format
Format specifier: %
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...
scheme-format
Format specifier: ~
Todo
Which parts of #Special_characters_and_other_tips would better stay here?
Orphaned Records
At the end of your file you might see records like
#~ msgid "Enter an Online Direct Debit Note"
#~ msgstr "Online-Lastschrift eingeben"

#~ msgid "Debited Account Number"
#~ msgstr "Konto-Nr. des Zahlungspflichtigen"

They have no reference line. This records are no longer in use and you can remove them.

Translate the strings

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.

Contexts
Important
With Gnucash 3.7 the first 2 forms got replaced by #Message Context. The description of the old types is only kept for some time to help updating older catalogs.

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: https://wiki.gnome.org/GnomeI18nDeveloperTips.

There are at least 2 use cases:

  • Abbreviations, i.e. for columns and their headers:
msgid "Reconciled"
msgstr "Abgeglichen"
:
msgid "Reconciled:R"
msgstr "Reconciled:A"
  • Sample text to determinate the size of the output cell. Instead of a translation the "worst case" of expected text in your language is required here.
For the following example the german tranlators copied the longest path of account names from their business account templates as shown in the accounts tab of Gnucash:
msgid "sample:Expenses:Automobile:Gasoline"
msgstr "sample:Aufwendungen 2/4:Reparatur/Instandhaltung:4805 Reparatur u. Instandh. von Anlagen/Maschinen u. Betriebs- u. Geschäftsausst."
Important
Keep the part before the colon untranslated.
Another form - without need to insert the prefix - was
#. Translators: This string has a context prefix; the translation
#. must only contain the part after the | character.
#: gnucash/gnome-utils/dialog-options.c:722
#: gnucash/gnome-utils/gnc-tree-view-account.c:908
msgid "Column letter for 'Placeholder'|P"
msgstr "P"
and became
#: gnucash/gnome-utils/dialog-options.c:719
#: gnucash/gnome-utils/gnc-tree-view-account.c:906
msgctxt "Column header for 'Placeholder'"
msgid "P"
msgstr "P"
Tip
A tool like kdiff3 can help you to recover your previous translation.
Message Context
In more recently written parts we use a message context:
#: libgnucash/app-utils/gnc-ui-util.c:903
msgctxt "Reconciled flag 'not cleared'"
msgid "n"
msgstr ""
Special characters and other tips

Depending on the context a few characters have a special meaning and need some special treatment:

"#" (hash)
In English it is often used as abbreviation for "Number". You should replace it by "No.", "Nr." or whatever is common in your language.
"_" (underline)
In menu and dialog entries the following character will become the accelerator, mnemonic or hotkey, which can be used together with a superkey [ctrl] or [alt] to jump to the entry. While in GTK2 they have always been visible, in GTK3 they appear only after holding the superkey. More specific under Linux you reach a main menu entry with [alt]+[key] and its submenus and other menu entries with [key]. In dialogs always use [alt]+[key].
The terminology is not unique here: while
msgfmt has a --check-accelerator option and
DocBook uses <accel> tag for a letter used with a meta key and <shortcut> for a key combination, but
GTK+ distinguishes the underline marked character of the label as mnemonic and the hotkeys like F1 for Help as accelerator.
So the key should be unique in its context and you should control it by #Running GnuCash with your file after #Compile & Install.
wrong:
"do _this" # Hotkey: t
"do _that" # Hotkey: t => not directly reachable
right:
"do th_is" # Hotkey: i
"do th_at" # Hotkey: a
That is one of the reasons why you should run the program with your translation: to see duplicate accelerators.
Characters to avoid
Already used on buttons like in English: Close, Help. Others depend on the context.
Characters breaking the baseline like in latin script: j,p,q,y. At least in some fonts the underline becomes invisible - leaving the user clueless.
In the headers of exported files
here it is used to link multiple words to one identifier together. Example:
#: ../src/import-export/csv-exp/csv-tree-export.c:155
msgid "full_name"
msgstr "Vollständige_Bezeichnung"
"\" (backslash)
It is the escape character in many programming languags. The following character has a special meaning like e.g.:
"\n" (New line)
The most often used special character in our strings. If msgid contains "\n" keep the layout and add them to msgstr too - at the same places.
"some \"quoted\" text"
Because " terminates the messages, you must precede it by a backslash inside of the messages or use other quoting characters like:
  • "some 'quoted' text"
  • "some »quoted« text"
  • "some „quoted” text"
You are free to use the conventions which are common or suggested in your language, but stay consistent. For that purpose you should add a translator comment about the convention at the beginning of the file for better cooperation.
Use "\\" to print a backslash.
"%" (percent)
In C based programming languages "%" marks the beginning of a format specifier, e.g. "%d6" means insert the next variable here in decimal format with 6 digits. Such format specifiers should be copied into your translated message, at the appropriate spot for your language. Boost's list of format flags for date and time is available at https://www.boost.org/doc/libs/release/doc/html/date_time/date_time_io.html#date_time.format_flags.
Non-ASCII digits
As a special feature for Farsi (Persian) and maybe Arabic, translators can insert an ‘I’ flag into numeric format directives. For example, the translation of "%d" can be "%Id". The effect of this flag, on systems with GNU libc, is that in the output, the ASCII digits are replaced with the ‘outdigits’ defined in the LC_CTYPE locale category. On other systems, the gettext function removes this flag, so that it has no effect.
Note
If a string is marked with c-format and has a % mark that does not start a format specifier, file a bugreport and tell the developers the location of the string (the lines above the msgid). The developers should fix this in the code. One way to do so is to insert a comment containing xgettext:no-c-format before the gettect call.
In order to continue without having to wait for the developers' fix to propagate you can remove the c-format flag from the #, comment line above. If no other flags are in the line, simply remove the line.
  • To output "%" if a string contains format specifiers, use "%%" in your string.
Reordering parameters
Assume a string "In %d cases the result will be %d.", but in your language you would prefer to write "%d will be the result in %d cases." Now you would get the wrong numbers.
Solution
Insert the ordinal number of the parameter, followed by "$" in the format specifier: "%2$d will be the result in %1$d cases.".
"~" (tilde)
like "%", but for scheme-format. The basic scheme-format uses ~a or ~s to format subsequent variables within code and should be copied in the translated message, in the same order. Guile's (ice-9 format) does reordering with the ~@* and ~#* arguments, but it's a bit tricky to use:
  (format #t "~@*1~a's ~@* from ~@*2~a to ~a" "Balance Sheet" "Yoyodyne Pty" "1 Oct 2018" "30 Sept 2019")
would print
  Yoyodyne Pty's Balance Sheet from 1 Oct 2018 to 30 Sept 2019
Note
~a will insert a contents using "human readable" (display var) whereas ~s will insert contents using (write var). This is an important difference which means ~a and ~s cannot be interchanged.[1]
"{num,optional other specifiers}"
this is a format specifier for C++ code. You cat either copy it verbatim somewhere in your translated message or you may adapt it to your language.
"&" (ampersand)
is the starting character of HTML encoding, which is used in some reports. E.g.
&nbsp;
means NonBreakableSpace.
"<" (less)
is the starting charcter of tags in several markup languages. E.g.
<b>Text</b>
results in bold Text.
See also
GUI Guidelines is the related programmers view.
Almost Done
If you are almost done it becomes harder to find the last untranslated messages. Then you can use
msgattrib --untranslated ${LL}.po
and then search your file for the content of the msgid.

Check syntax and statistics of your .po file

Required
msgfmt -c --statistics ${LL}.po

If that program reports one or more fatal errors for your language, you should review the criticized lines of your file.

Tip
A successful call will create a file messages.mo. If you are not using a build environment, you can move that file to
Linux
${PREFIX}/share/locale/${LL}/LC_MESSAGES/gnucash.mo
and restart gnucash to test the program with your translation.
Desired

In a second run you might wish to see, where you forgot to add an accelerator:

msgfmt -c --check-accelerators="_" --statistics ${LL}.po

The users will love you if you fix them, too.

Current status

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

To see some over all 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.

Priority

As you might have noticed, the po file for GnuCash is rather big by containing more than 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.
Tip
If you wish to see the string from a *.glade.h file in it's context, but don't know, where it is hidden in gnucash, you can open the file gtkbuilder/*.glade with Gnomes interface builder Glade.
  • Low Priority: Strings from all *.schemas.h files will not appear in the gnucash UI. Instead, they are shown only inside the
  • Linux: dconf-editor,
  • macOS: defaults or
  • Windows: regedit program when the user wants to set particular GSettings keys of GnuCash. You can safely consider the .schemas.h strings with lower priority than the others.
    • Register2 feature is a stalled developement. The strings are only visible, if you #configure --enable-register2. Some, but not all strings are marked with a "Register2 feature" comment.

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.

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

msgfmt -c --statistics LL.po

Above call will report most important errors in your .po file and must not fail, while the call below

msgfmt -c --check-accelerators="_" --statistics LL.po

whill additionally check if you missed some keyboard accellerators aka hotkeys.

Note for developers
Another python based tool is i18nspector - checking tool for gettext POT, PO and MO files. It is stricter and shows also warnings about expected entries which our .pot file is currently missing. That can be discussed e.g. in #Background.

If you want to see your translations within a running version of gnucash, simply place your .po file in the po/ directory of your local gnucash repository (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-git/bin/gnucash

To review the schema strings you can use

since 2.6
dconf-editor
until 2.4
gconf-editor.


Alternative Way with Poedit

If you use Poedit while working on .po file, you would notice that it saves file in .mo format, the very format that GnuCash uses itself. So one would just need to copy this LL.mo file into appropriate subdirectory under /opt/gnucash-git:

 cp LL.mo /opt/gnucash-git/share/locale/LL/LC_MESSAGES/gnucash.mo

The only thing that needs to be changed here is LL which stands for your language code (ka Georgian, de German etc). The rest is as in above method:

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

Submitting

Only if

  • you want to send your file to the Translation Project or
  • it did not exist before and you want to send it via mailing list, create a gzipped version of it:
gzip XXXX.po
Do the same with your #The glossary file.

In all other cases just push your commit (Git#Pull Requests) or upload the Git#Patches of the files. There should be one commit/patch containing the noise as described in #Update an existing .po file and a second one containing your actual work.

Then follow #How to submit changes directly to GnuCash.

Alternatively, you could submit the finished translation via the GNU Translation Project. See the instructions on https://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.

See also https://lists.gnucash.org/pipermail/gnucash-devel/2009-January/024700.html [FIXME: obsolete?]

Committers

msgid "translator-credits"
should contain at least the "Last-Translator:" from the header.
msgid "gnucash-icon"
do not translate, we have only one.
If you there click on 2.6.5 you will get a fresh gnucash-2.6.5.pot, while we have already an ar.po with 2031 translated and 4 fuzzy messages. By contrast on the as external marked https://translationproject.org/team/de.html, you see:
gnucash 	2.6.5 	unknown 	external
and will not get a new pot file.
But we can bundle this notes with the release announcement, if you add the language to Release Process#TP Status changes.
  • On committing add the name and email address of the last translator from the file as author, e.g.
 git commit --author="Lieutenant Worf <lt.worf@starfleet.org>" --message="L10N:tlh[: optional status or other details]

4677 translated messages." # << The msgfmt statistics
  • If you check in a new language, remove a language or see the status of the language changes from partial to (almost) complete, update the numbers in <sect2 id="oview-featuresintl2"> in file guide/C/ch_oview.xml of gnucash-docs.

Problems

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-git/bin/gnucash-env gdb /usr/bin/guile

Then, from within gdb, issue:

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

Eventually, gnucash should crash (because 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.

Watch File accesses

To follow gnucash as it access files,

strace /opt/gnucash-git/bin/gnucash

Thank You

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

How to translate the Windows Installer

See Windows Installer Translation.

Check Files in Repo gnucash's doc Directory

Note
The content of this directory got some cleanup by bug 797111.

In theory one could create localized man pages (<command>.<man-section>[.in]). But their content is almost the same as <command> --help, which are translated for gnucash and gnucash-cli.

Task
We should use gettext also in the perl modules.

Translating the GnuCash Guide and Help

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

  • Tutorial and Concept Guide: This is an introduction in the basic principles of double entry accounting and their application in GnuCash. This text is really useful for new users.
  • Help: This is the context sensitive help system.

If you are interested in translating these documents, please decide whether you want only to translate the existing text or whether you want also to improve and cross-check the text with the actual status in the program in your language. It is less effort only to translate the text, but you also run into the risk of doing unnecessary work if you translate explanations which are no longer correct. It might be more effort to create a new text in your language, using the English text only as an inspiration, but it will surely lead to more useable and more helpful documentation. We, the programmers, encourage you to do the latter and create a new text in your language. As you are the one doing the work, the decision is up to you.

Both documents consist of

  • text files in an XML format called DocBook, where the complete document is split into a collection of xml files by chapter, and
  • images:
    • In the few scalable vector graphics (SVG) you can replace the text in you localized file.
    • But most are screenshots stored as Portable Network Graphics (png) files in the subdirectory figures/. The xml files will contain links to the png files where they should appear in the text.
See also
Documentation Update Instructions#Screenshots and Images

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

You can find an introduction to DocBook in Creating DocBook Documents.

Please use a unified terminology: The translator of the program messages should have created #The glossary file for the translations of the key wordings in the program. Please make sure to use the same terms in the documents, too.

You can check the nightly builds - in particular after your updates were committed.

Prerequisites

Linux

In addition to the software for running autogen.sh, the following additional software is needed for the development on Linux. From the gnucash-docs/README file as of 2019-02-19:

  • libxml2
  • libxslt [Debian packed the required xsltproc in a separate package,
which depends on libxslt]
  • docbook-xsl
  • rarian or
scrollkeeper >=0.3.4 (its ancestor)
  • yelp (for viewing)
Optional:
  • gnome-doc-utils (contains xml2po for the use of po editors like in the it translation)
Additional Requirements for Generating Mobipocket:
Additional Requirements for Generating chm:
Additional Requirements for Generating PDF:
  • Apache fop >= 0.95
For the Japanese PDF, Japanese fonts are included. If you want to use other Japanese fonts you can use the --with-japanese-fonts-dir, --with-japanese-mincho-ttf, and --with-japanese-gothic-ttf configure options to select them. fop's TTFReader can't, as of version 1.1 anyway, handle OpenType fonts.

Note for wiki editors: Keep above section in sync with gnucash-docs/README

Other Operating Systems

Wm says the section below is being edited and not yet complete, see the thread "Help with help" in gnucash-devel for more info


macOS

At present we do not know of a suitable DocBook file toolset for macOS though a *nix on Mac approach may / should work. We encourage solutions so if someone could document this we would be grateful [Wm: aside is this redundant? Don't most modern Macs include *nix so instructions similar to those I have provided for Win might apply?]

Windows

One way of being able to edit and produce DocBook files on Windows is to use the *nix instructions under cygwin. Instructions for obtaining a suitable toolset follow

  • Get cygwin by going to https://www.cygwin.com and pressing the link for the setup-*.exe file suited to your system
  • save it, virus scan it, etc. as you see fit then run it
  • type "libxslt" into the search box
  • expand Libs and press Skip so that it shows a version for all 3 GNOME XSLT Library options, you want the most recent which it will offer by default, cygwin will work out the gndependencies
  • you may follow similar steps to obtain git, i.e. type "git" into the search box, expand and tick the obvious candidates
  • Note: because these are *nix type text based utilities you are downloading hundreds of kiloBytes not megaBytes; relax, this isn't Windows Update, a few extra progs won't kill your system, promise
  • click next at the bottom rhs and let cygwin do its stuff; this may take some time depending on connection speeds at both ends
  • Aside: if you get a msg about "Package: Unknown package / inetutils.sh exit code 1" you may ignore it, after reading the full blurb, of course, my advice is not to try and track it down unless you have a lot of spare time on your hands
  • When it is done fire up cygwin and do stuff as per the *nix instructions

Further details:

  • don't look for
  • yelp (the viewer)
  • on cygwin: it isn't there; it is an old prog (last updated in 2007, I think
wrong, see https://download.gnome.org/sources/yelp/ for the origin and https://cygwin.com/packages/summary/yelp.html for cygwin. --Fell 17:21, 26 October 2013 (EDT)
) and should probably not be regarded as current though it may be useful if you have it on another OS
[Wm:
  • I wonder how many current *nix users have it?
AFAIK it is still part of the GNOME desktop: google search for yelp+gnome --Fell 17:21, 26 October 2013 (EDT)
Should ref to yelp be made less prominent?
It is the only way I know to get some context sensitive help from inside GnuCash. --Fell 17:21, 26 October 2013 (EDT)
]

Wm says the section above is being edited and not yet complete, see the thread "Help with help" in gnucash-devel for more info

Java (all OS)

Eclipse has

  • several Git plugins,
  • a C Development Tool with autotools support,
  • a feature rich, builtin XML editor and a few plugins like XML WYSIWYG editors

or in other words, all what is needed here, available.

The Procedure

First, you have to download the most recent version of the gnucash-docs package. This is done as follows:

  1. Checkout the documentation in a directory gnucash-docs:
    git clone https://github.com/Gnucash/gnucash-docs -b maint gnucash-docs
  2. Create your working branch. If you plan to use pull requests, you should use unique names like guide-LL-chapter-x-part-n instead of working-branch.
    git checkout -b working-branch
  3. Create a new directory (if it doesn't already exist) in guide/<locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_PT. See #Naming Conventions.
    See Locale_Settings#IETF_language_tags for details.
    If your translation is the first for your language do not add a region code. So also other regions benefit from your translation.
    And copy the files from guide/C into this directory:
    cp -r guide/C guide/LL
    Not in latin letters written languages
    They need additinal files to process printing to pdf. See ja or ru as examples.
  4. Add the directory you created to [gnucash-docs/]configure.ac (as a new line guide/<language>[_<region>]/Makefile under AC_OUTPUT) and [gnucash-docs/]guide/Makefile.am (at the end of SUBDIRS).
  5. Notify git about the new directory and files. "*" is quoted by "\".
    git add guide/LL/\*.\*
  6. Now the real work:
    1. Edit all the xml files (see #DocBook xml editors below for suitable editor programs) and translate them into your language.
      • In the event the english documents get updated, it might be useful to have a comment in the header of each chapter in the form:
      <!-- Translation based on maint/master commit 1234567 2014-01-01 10:00 UTC -->
      
      Then you can later view a diff between the current and that version of the english file in one window to locate the changes and adjust the translation in another window. Some translators like to do also the translation in a graphical diff program like KDiff3 between english and their language because the <sectN id>s will synchronize the text.
    2. Adjust gnucash-{guide|help}-<lang>.omf. This file follows Open Metadata Framework (OMF), a subset of the Dublin Core description for metadata. See Writing ScrollKeeper OMF Files for details like mandatory standard elements. Without this file your document will not show up in yelps index page. At some point in the future we might extract this data automaticly from the docs using Gnome Doc Utils.
      Currently it is also necessary to replace in {guide|help}/<lang>/Makefile.am the "C" in both occurrences of $(docname)-C.omf by <lang>.
    3. 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.
    4. In addition to the text, you need to recreate the image files in guide/C/figures so that they are appropriate to your language. For details (size, style,...) see Documentation_Update_Instructions#Screenshots_and_Images.
      1. 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.
      2. A few figures are in scalable vector graphic (svg) format. Here you can edit the files e.g. in Libre/OpenOffice and translate the strings and adjust the size.
    5. 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, or at least file a bug against it, 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 file a patch, which adds your name and email address to AUTHORS, so you will become famous. ;-) Ask to apply this latter patch also against gnucash/DOCUMENTERS because both files should have the same content. More details about editing the english text can be found in the Documentation Update Instructions.
  7. Test your xml files for 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.
    Tip: Some xml aware editors have a menu entry like validate to run this test.
  8. Optional: test your work with yelp - there are build system methods to support you. The exact steps differ based on the build system you choose:
    1. Using a terminal, go to your gnucash-docs directory
      cd /path/to/gnucash-docs # replace the example path with your real path
      
    2. Make a build directory and go into it
      mkdir build
      
    3. Setup a build system of choice
      # Run this for the autotools based build system (deprecated!)
      ./autogen.sh
      cd build
      ../configure --PREFIX=../install
      # Or run this for the cmake based build system (preferred)
      cd build
      cmake -D CMAKE_INSTALL_PREFIX=../install
      
      There are plenty of other options you can pass to either configure or cmake, but that's outside of the scope of this wiki page.
    The steps above only have to be run once (though running it more than once is safe). What follows can be repeated as often as needed while working on the docs.
    1. To check your work while editing you can run
      make check
      
      in the build directory. That will However check all documentation, not just the one you're working on.
    2. If you want to check only your work a different command is needed depending on your build system. Each command starts from the top-level of the build directory and in this example we will check work on the German version of the guide:
      # Run this for the autotools based build system (deprecated!)
      (cd guide/de && make check)
      # Or run this for the cmake based build system (preferred)
      make de-gnucash-guide-check
      
      This will run the xmllint command above over the full directory structure. As an aside you can generate the documentation in other formats, like pdf or html by replacing check in the commands above with pdf or html respectively:
      # Run this for the autotools based build system (deprecated!)
      (cd guide/de && make pdf)
      # Or run this for the cmake based build system (preferred)
      make de-gnucash-guide-pdf
      
    3. In order to be able to see your work in yelp you still have to install it. From the build directory run:
      make install
      
    4. To see your work in yelp use the following command
      # In the command below, replace
      # <language> with the language of the doc you want to view, for example C (for English), de (for German),...
      # /path/to/gnucash-docs with the real path to the source directory for your documentation
      # <docname> with the document you wish to view, either gnucash-help or gnucash-guide
      LANG=<language> XDG_DATA_DIRS=/path/to/gnucash-docs/install/share:${XDG_DATA_DIRS}:/usr/local/share:/usr/share yelp gnome-help:<docname>
      # Example:
      LANG=pt XDG_DATA_DIRS=/path/to/gnucash-docs/install/share:${XDG_DATA_DIRS}:/usr/local/share:/usr/share yelp gnome-help:gnucash-guide
      
      This uses yelp's built-in mechanism to select the proper language.
    5. Alternatively you can open the installed document directly via:
      yelp /path/to/gnucash-docs/install/share/gnome/help/<docname>/<language>/<docname>.xml
      
      You need to make the same replacements as in the other form.
    6. Repeat these steps until you're satisfied with the result.
  9. Update the branches of your local repo often:
    git checkout maint # switch to maint
    git pull --rebase # update it
    git rebase maint working-branch # update working-branch
    git checkout working-branch # switch back to working-branch
  10. Follow #Submitting your work direct to GnuCash.

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

Committers: If it builds fine, add the directory changes from 2. also to gnucash/maint/packaging/win32/install-impl.sh and merge the change to master, if required.

DocBook xml editors

For editing these DocBook xml files, various editors can be used: https://en.wikipedia.org/wiki/DocBook might contain pointers to some, or also https://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html.

Some developers use Eclipse.
The german wikipedia says the translation tool OmegaT can work on docbook.

People have said that AbiWord and OpenOffice / LibreOffice have support for DocBook available, in which case you could directly edit gnucash's xml files with those. However, those editors will probably not work with the current multi-file setup where each chapter is in a separate XML file and the main XML file contains points to the chapters' files. As a workaround, you can copy the relevant parts of the main XML file into the chapter's file by a plain text editor so that it "looks like" one single DocBook document. This can be opened with OpenOffice/LibreOffice and edited as normal. After that, the added parts from the main file need to be removed again, and then you have the edited chapter text.

Using po editors

Some translators are more familiar with using po file editors like poedit, Kbabel, Gtranslator etc. For those people, it is possible to convert the content of the help documents (the DocBook XML files) into po files, translate the messages in the po file, and convert the result back into xml. This section describes how to use this approach for the gnucash help documents.

The downside of this approach
It will be much harder for the documenters to fix e.g. broken links in times where you are inactive.

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.
  1. Do the conversion 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
  2. Translate helpfile.xml.xx.po using your favorite po editor.
  3. Convert back to xml:
    xml2po -e -p helpfile.xml.xx.po -o xx_helpfile.xml helpfile.xml
  4. Test your translated xml file as mention above:
    xmllint --valid --noout xx.helpfile.xml
  5. 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]

GnuCash Maintainer Tasks

For new languages the core developers have some additional tasks:

New Script

Check make pdf! Do we need additional TTFs?

First Nightly

Ask the admin of code.gnucash.org to create the new directory.

First Release

Adjust htdocs ...

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.

Preliminary Considerations

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 region 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:

In this section always replace <locale> with your language code and optional your region code, if there are multiple countries with the same language and your templates are fitting only to one of them.

Prerequisite

Initialize accounts/<locale>

  • If it does not already exists, execute the following steps to initialize your accounts/<locale> directory:
  1. Copy the directory accounts/C to accounts/<locale>
  2. In the directory accounts/ change the file CMakeLists.txt and add your <locale> to both alphabetical sorted lists:
    1. add_subdirectory(C)
      :
      add_subdirectory(<locale>)
      :
      
    2. set(accounts_DIST ${C_DIST} ...  ${<locale>_DIST} ... ${dist_list} PARENT_SCOPE)
      
  3. In accounts/<locale>/CMakeLists.txt adjust the <locale>:
    :
    set_dist_list(<locale>_DIST ${dist_account_DATA} CMakeLists.txt)
    
    install(FILES ${dist_account_DATA} DESTINATION ${ACCOUNTS_INSTALL_DIR}/<locale>)
    file(COPY ${dist_account_DATA} DESTINATION ${ACCOUNTS_BUILD_DIR}/<locale>)
    
    Note
    The next 2 steps are are discussed in #Localize the Account Charts below.
  4. Localize acctchrt_full.gnucash-xea. This is only a helper file where you have all accounts in their context.
  5. Now create the real modules by merging the respective parts from acctchrt_full.gnucash-xe in the other acctchrt_*.gnucash-xea files.
  • If you remove or create new files, adjust in accounts/<locale>/CMakeLists.txt the list
    set(dist_account_DATA
      ...)
    
  • Whenever you changed one or more CMakeLists.txt files, you have to rerun
    cd ${SOURCEDIR}
    cmake <your options>
    cd ${BUILDDIR} # e.g. .build
    make # or ninja
    

Localize the Account Charts

Tip: C/acctchrt_full.gnucash-xea is a helper file. Because we prefer modularization it usually is not part of the distribution. It contains the full tree of the personal en_US accounts. The other acctchrt_*.gnucash-xea files contain single branches of that. So after translating it you can copy&paste the respective parts in the other files to ensure consistency between them.

If you modularize the templates you should start with acctchrt_common.gnucash-xea - it is the most basic.

For each desired acctchrt_* file in that directory:

  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
    1. translate the act:name, and act:description fields.
    2. Optionally you can
      1. assign an account number <act:code>1234</act:code> after <act:commodity-scu> or
      2. add a note as i.e. in
           <act:slots>
            <slot>
              <slot:key>hidden</slot:key>
              <slot:value type="string">true</slot:value>
            </slot>
            <slot>
              <slot:key>notes</slot:key>
              <slot:value type="string">Some additional text about the usage of this account</slot:value>
            </slot>
            <slot>
              <slot:key>placeholder</slot:key>
              <slot:value type="string">true</slot:value>
            </slot>
          </act:slots>
        
    Please do not translate any other fields or the internally used ROOT account.
  3. To avoid typos, run the AccountHierarchyTemplate#Syntax Check.
  4. New files to be shown to the user must be added to the account_DATA section,
    helper files like acctchrt_full.gnucash-xea to EXTRA_DIST in Makefile.am.

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 wish to add new accounts manually, you will need some additional guids, those funny random numbers. To get them you can use:

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

or use an online uuid generator like this one (any other one will do as well). Be sure to untick "Hyphens" to generate gnucash compatible guids. If you forget or the site you use doesn't offer that option, simply remove the hyphens yourself.

Dependencies
uuidgen is in a package 'util-linux', sed has its own package.

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

Test your Work

To test your work under real conditions, you should finally Compile & Install it. But before you need an adjusted Makefile.am in your accounts/<locale> directory. If none exists, copy that from accounts/c and adjust it:

  • 1. Line (accountdir): adjust the locale.
  • If you removed accountcharts, remove their line from account_DATA,
  • if you added new files, insert lines with their names and "\" (the line continuation symbol).

How to create localized Income Tax Tables

Note
This section is under developement and mostly untested!

As of the beginning of 2015 there is an nice US tax module with a report and export in TXF format. Additional there is a small de_DE derivate for the monthly VAT declaration. you can compare them to see, how you can tweak them to get something else.

Tax Table

From https://github.com/Gnucash/gnucash/blob/maint/src/tax/us get the files

  • txf.scm - the tables, and
  • txf-help.scm - the descriptive help strings for each TXF code. This is also used to get a table in gnucash-docs/help/

They have relative simple table structures:

(define txf-tax-entity-types 

contains a list of forms for different entities (person, company,...).

(define txf-income-categories ...
(define txf-expense-categories ...

contain for each of the above lists the entries. If you compare this file with the respective *_DE file, you can see an example localization with additional categories:

(define txf-asset-categories ...
(define txf-liab-eq-categories ...

It should be possible to adapt the lists for your tax forms. Then you might submit them to an enhancement request in buzilla, product:Gnucash, component:TXF Export.

Report and Export

Probably you need to have other export reports. That are in https://github.com/Gnucash/gnucash/tree/maint/src/report/locale-specific/us like

  • txf-export.scm
  • us.scm is unused

Here you might probably need some help from a programmer.

How to translate the website

Note about OS
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[-w64]), but that's untested so far. Please report your findings here.
  • Get a checkout of https://github.com/Gnucash/gnucash-htdocs
  • Run the command
    make pot
    
  • Then depending on whether or not a translation for you language exists already (complete or not):
    Existing translation

    Run the command
    msgmerge --previous -U po/LL.po po/gnucash-htdocs.pot
    
    where LL is your language code, see #Naming Convention above.
    Alternative
    make msgmerge
    
    will update all .po files
    New translation

    In the po directory run
    As translator
    msginit
    
    This will insert your name, email and locale settings into the new file. If that fails copy the newly created file po/gnucash-htdocs.pot to po/LL.po, where LL is your language code, see #Build a new .po file earlier.
    As maintainer
    # Set LL=<language code>
    msginit --no-translator --locale=$LL
    
    This will create a new file $LL.po without personal data. Continue with #Maintainers Task.
  • Translate the po/LL.po file as described in #Translating the .po file.
    Priority
High
Startpage: {index|externals/*}.phtml
Low
sizing.phtml (outdated) search/templates/NMZ.* (unused)
Medium
the rest depends on you.
  • Run
    msgfmt -c --statistics po/LL.po
    
    to see your success.
  • Optionally run
    recode -d <input_encoding>..h0 po/LL.po
    
    to get special characters HTML quoted.
  • Send your LL.po either as
    • GitHub Pull Request or
    • attachment of a Bugzilla enhancement request to the mainteiner team.

Maintainers Task

For new languages adjust the appropriate

  • git add po/LL.po
    
  • Makefile,
  • lang.php,
  • externals/header.phtml rules,
  • copy the directory news/en to news/<ll> and
  • create locale/<ll>.

To make the changes visible, you will have to

  • run
msgfmt -c --statistics po/<ll>.po -o locale/<ll>/LC_MESSAGES/gnucash-htdocs.mo
or to compile all translations
make mos
  • and include the mo file(s) in your commit.

Tips for Developers

This section moved to I18N.

Project Maintainers

Some notes for Maintainers:

When to msgmerge

Some translators complain, it is so hard to update .po files. When should we do it?

From https://translationproject.org/html/robot.html
The Translation Project robot is not allowed to update the registry with new information about maintainers, languages, or translators, nor is it allowed to process POT files. These things are still handled by hand. When a new POT file is being registered by a project coordinator, the registering script calls msgmerge when previous translations exist, so translators are notified of a PO file which is up-to-date. New POT files are announced automatically to a team's mailing list, if the team has asked for this feature.

So for $TP_LINGUAS it is done on each release. Probably we should do it, too?

Merging with divergent source trees

The source tree in GnuCash 2.7 was thoroughly restructured, so it is now very different from 2.6. One side effect of this is that the MsgIds in our 2.7 *.po files are in a completely different order compared to 2.6. This means git merge of maint in unstable will break the 2.7 *.po files. So when merging from 2.6 to 2.7 we have to ignore all changes in the maint po files at this point. To rescue at least parts of the work, try this.

# Set your language in LL, e.g.: export LL=de
# while you are in the maint branch save your .po file outside of the repo e.g. as maint."$LL".po
git checkout unstable
git merge maint                                       # resolve the full LL.po merge by using the unstable version of LL.po (other files can be merged as normal)
cd ../build                                           # assuming ../build is your build directory
make pot                                              # update the template with changes from maint
cd ../src/po                                          # assuming src is your gnucash git repo
msgmerge "$LL".po ../build/po/gnucash.pot -o "$LL".po # update the po of your $LL
msgcat --use-first "$LL".po ../<path_to>/maint."$LL".po -o "$LL".new.po

For the best result you might test different msgcat parameters. Finally

mv "$LL".new.po "$LL".po

Background

This section was started to get some overview, work in progress! Beyond it helped to get rid of the outdated #IntlTool in version 2.7.6. For details see the GetText Manual.

Packages

In our build process we use beneath self written scripts the following packages:

  • glib2-devel: glib-gettextize
  • gettext, probably broken in:
    • -runtime: msgfmt, ...
    • -tools: (autopoint), gettextize, msg*, xgettext, ...
    • -runtime-tools-doc: manuals etc.
  • (only up to 2.7.5) intltool: Intltool*

Our Build Process

This was the old (upto 2.6) autotools build process, which went through the following scripts:

autogen.sh
Note
Autotools were only used up to 2.6 branch. 2.7 and later use CMake instead.
glib-gettextize
helps to prepare a source package for being internationalized through gettext. It is a variant of the gettextize that ships with gettext.
glib-gettextize differs from gettextize in that it doesn't create an intl/ subdirectory and doesn't modify po/ChangeLog (note that newer versions of gettextize behave like this when called with the --no-changelog option).

»Note that on GNU systems, you don't need to link with libintl because the gettext library functions are already contained in GNU libc.« (glibc) [3]

configure.ac
  • Sets
ALL_LINGUAS= ...

In recent versions it can be substituted by LINGUAS files in the po directories. We should consider this to distinguish TP vs. GC maintained translations.

GETTEXT_PACKAGE=gnucash

This is intltool style. Gettext uses PACKAGE=...

AC_SUBST(GETTEXT_PACKAGE)
AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, "$GETTEXT_PACKAGE",
   [GetText version number])

AM_GNU_GETTEXT_REQUIRE_VERSION|AM_GNU_GETTEXT_VERSION(x.yy.zz) can be used to require a version. We should use it to avoid ...

  • TP expects > 0.11.
  • gnulib expects >= 0.17
  • RHEL7 offers 0.18.2 (RHEL6 0.17)
  • Debian Stable offers 0.18.1 and in backport 0.19.3
  • Glade2 msgctxt and Glade3 were implemented in 0.18.3 - July 2013
  • GSettings and Desktop entries are implemented in 0.19 - June 2014
  • and got bugfixes until Version 0.19.3 - October 2014
  • Scheme format strings got a fix in 0.19.4 - December 2014
  • AppData support: gettext-0.19.6 released - 2015-09
  •  ? custom XML formats in 0.19.7
<gjanssens> GtkUIManager files don't contain translatable strings as far as I know. They're not in POTFIILES.in either.

This setting then can be used by autoPoInt. Watch the caveaets from https://www.gnu.org/software/gnulib/manual/html_node/gettextize-and-autopoint.html:

On the other hand, if your package is not as concerned with compliance to the latest standards, but instead favors development on stable environments, the steps are:
  1. Determine the oldest version of gettext that you intend to support during development (at this time, gnulib recommends going no older than version 0.17). Run autopoint (not gettextize) to copy infrastructure into place (newer versions of gettext will install the older infrastructure that you requested).
  2. Invoke gnulib-tool, and import the gettext-h module. # Fixme: Meaning?
Regardless of which approach you used to get the infrastructure in place, the following steps must then be used to preserve that infrastructure (gnulib’s bootstrap script follows these rules):
  1. When a script of yours run autopoint, invoke gnulib-tool afterwards.
  2. When you invoke autoreconf after gnulib-tool, make sure to not invoke autopoint a second time, by setting the AUTOPOINT environment variable, like this:
$ env AUTOPOINT=true autoreconf --install
AM_GLIB_GNU_GETTEXT          # FIXME: Meaning?
  • runs checks with settings
    • AC_PROG_INTLTOOL
    • AC_CHECK_HEADERS(ltdl.h, ...
dnl Make sure we have a proper gettext installed
AC_MSG_CHECKING(for a valid gettext/gmsgfmt installation)
if test "$gt_cv_have_gettext" != "yes" || test "x$GMSGFMT" = "x"; then
  AC_MSG_RESULT(no)
  AC_MSG_ERROR([Cannot find Glib Gettext.  Maybe you need to install the gettext package?])
else
  AC_MSG_RESULT(yes - $GMSGFMT)
fi
makefile.am

has the following section:

.PHONY: pot
pot: Makefile po/POTFILES.in
	rm -f po/$(PACKAGE).pot
	${MAKE} -C po $(PACKAGE).pot


$(srcdir)/po/POTFILES.in: make-gnucash-potfiles .potfiles
	if test -w $(srcdir)/po/POTFILES.in ; then ./make-gnucash-potfiles > $(srcdir)/po/POTFILES.in ; fi

# Creation rules so that po/gnucash.pot can always be created for
# make dist.
po/gnucash.pot: po/POTFILES.in
	${MAKE} -C po gnucash.pot

.potfiles:
make-gnucash-potfile.in

This is a self written perl script from the time as gettext had several issues. It creates po/potfiles.in, the "list of files which contain translatable strings". This script is not used in a cmake based build environment for gnucash. As gnucash 2.7.4 and more recent is cmake only, this file has been removed starting from that release.

xgettext
xgettext
Extract translatable strings from given input files. See --language for supported list:
--language=NAME
recognise the specified language (C, C++, ObjectiveC, PO, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Smalltalk, Java, JavaProperties, C#, awk, YCP, Tcl, Perl, PHP, GCC-source, NXStringTable, RST, Glade, Lua, JavaScript, Vala, Desktop)
Options, which we should check:
--copyright-holder=STRING
set copyright holder in output
--foreign-user
omit FSF copyright in output for foreign user
--msgid-bugs-address=EMAIL@ADDRESS
set report address for msgid bugs