Difference between revisions of "Documentation Translation"

From GnuCash
Jump to: navigation, search
(Adapt for restructured source and build directories)
Line 12: Line 12:
 
:programmers: [[I18N]] and
 
:programmers: [[I18N]] and
 
:project maintainers: [[Language Administration]].
 
:project maintainers: [[Language Administration]].
 +
 +
;Note: The instructions below have been adapted for the documentation related to GnuCash 5.0 or more recent. This includes the ''master'' branch in git at the time of this writing. If you are looking or instructions to improve older documentation releases, please refer to [https://wiki.gnucash.org/wiki/index.php?title=Documentation_Translation&oldid=20988 an older version of this page].
  
 
== Translating the GnuCash Guide and Help==
 
== Translating the GnuCash Guide and Help==
 
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:
 
* ''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.  
 
* ''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.  
−
* '''Manual, ''' old name: ''Help'': This is the context sensitive help system. The renaming is in progress. The sources already use <tt>manual</tt>, but the installed document is still <tt>gnucash-help</tt>.
+
* '''Manual, ''': 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.
+
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 usable 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  
Line 116: Line 118:
 
|guide||manual||source directory name
 
|guide||manual||source directory name
 
|-
 
|-
−
|gnucash-guide||gnucash-help||document name
+
|gnucash-guide||gnucash-manual||document name
 
|}
 
|}
 
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:
Line 122: Line 124:
 
# Checkout the documentation in a directory ''gnucash-docs'':
 
# Checkout the documentation in a directory ''gnucash-docs'':
 
#: <syntaxhighlight lang="sh">git clone ${URL} -b maint gnucash-docs</syntaxhighlight> with ${URL}={{URL:GH}}Gnucash/gnucash-docs
 
#: <syntaxhighlight lang="sh">git clone ${URL} -b maint gnucash-docs</syntaxhighlight> with ${URL}={{URL:GH}}Gnucash/gnucash-docs
−
# 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 your working branch. If you plan to use pull requests, you should use unique names like ''LL-guide-chapter-x-part-n'' instead of working-branch.
 
#: <syntaxhighlight lang="sh">git checkout -b working-branch</syntaxhighlight>
 
#: <syntaxhighlight lang="sh">git checkout -b working-branch</syntaxhighlight>
−
# Create a new directory (if it doesn't already exist) as guide/<locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_PT. See [[#Naming Conventions]]: <syntaxhighlight lang="sh">
+
# If this is the first gnucash document in your language,
−
mkdir -p ${COMPONENT}/${LOCALE}
+
:# Create a new directory (if it doesn't already exist) as <locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_PT. See [[#Naming Conventions]]: <syntaxhighlight lang="sh">
 +
mkdir -p ${LOCALE}
 
</syntaxhighlight>
 
</syntaxhighlight>
 
#: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.
−
#:And copy the files from guide/C into this directory: <syntaxhighlight lang="sh">cp -r guide/C guide/LL</syntaxhighlight>
+
:# Copy CMakeLists.txt from C into your LL/ directory
−
#:;Not in latin letters written languages: They need additional files to process printing to pdf. See <tt>ja</tt> or <tt>ru</tt> as examples.
+
:# Inside CMakeLists.txt adjust the locale string in the first line of this file to match your directory name.
−
# Add an entry for your directory in [guide/]'''CMakeLists.txt'''. The format is <syntaxhighlight lang="cmake">
+
:# Adjust the following two lines (the ones starting with add_directory). Prepend both with a ''#'' sign. That will disable these documents in your language for now. We'll re-enable them as we add the proper document directories later on.
−
add_directory(<language>)
+
# Add an ''add_directory'' entry for your language in '''CMakeLists.txt''' in the ''toplevel'' of your source directory. The format is <syntaxhighlight lang="cmake">
−
</syntaxhighlight>. There are other examples in those files you can follow. Please keep the language list sorted alphabetically.
+
add_directory(<language>)</syntaxhighlight>. There are other examples in that file you can follow. Please keep the language list sorted alphabetically.
 +
#Copy the guide directory from C (English language) into this directory: <syntaxhighlight lang="sh">cp -r C/guide LL/guide</syntaxhighlight>
 +
#:;For languages that don't use latin characters: They need additional files to process printing to pdf. See <tt>ja</tt> or <tt>ru</tt> as examples.
 
# Notify git about the new directory and files. "*" is quoted by "\".
 
# Notify git about the new directory and files. "*" is quoted by "\".
−
#: <syntaxhighlight lang="sh>git add guide/$LL/\*.\*</syntaxhighlight> or <syntaxhighlight lang="sh>git add manual/$LL/\*.\*</syntaxhighlight>
+
#: <syntaxhighlight lang="sh>git add LL/CMakeLists.txt LL/guide/\*.\*</syntaxhighlight> or <syntaxhighlight lang="sh>git add LL/CMakeLists.txt LL/manual/\*.\*</syntaxhighlight>
 
# Now the real work:  
 
# Now the real work:  
−
## Edit '''all the xml files''' (see [[#DocBook xml editors]] below for suitable editor programs) and translate them into your language.
+
## Edit '''index.docbook and 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:
 
##* 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>
 
##: <syntaxhighlight lang="xml"><!-- Translation based on maint/master commit 1234567 2014-01-01 10:00 UTC --></syntaxhighlight>
Line 145: Line 150:
 
##:* the [{{URL:GH}}Gnucash/gnucash/tree/maint/po/glossary glossary directory at GitHub].
 
##:* the [{{URL:GH}}Gnucash/gnucash/tree/maint/po/glossary glossary directory at GitHub].
 
## <s>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.</s> Obsolete?
 
## <s>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.</s> Obsolete?
−
## 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 Other Images]].
+
## In addition to the text, you need to ''recreate the image files in '''C/guide/figures''''' so that they are appropriate to your language. For details (size, style,...) see [[Documentation_Update_Instructions#Screenshots And Other 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.
 
### 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.
 
### 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.
 
## 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 your xml files for 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''' ''index.docbook'', e.g.:
 
#: <Syntaxhighlight lang="sh">
 
#: <Syntaxhighlight lang="sh">
 
cd ${gnucash-docs-dir} # adjust to navigate to your local gnucash-docs source directory
 
cd ${gnucash-docs-dir} # adjust to navigate to your local gnucash-docs source directory
−
xmllint --postvalid --xinclude --noout --path docbook guide/>LL>/gnucash-guide.xml # replace <LL> with your language code
+
xmllint --postvalid --xinclude --noout --path docbook <LL>/guide/index.docbook # replace <LL> with your language code
 
</Syntaxhighlight>
 
</Syntaxhighlight>
 
#: The program ''xmllint'' is part of the package '''libxml'''.
 
#: The program ''xmllint'' is part of the package '''libxml'''.
 
#: '''Tip:''' Some ''xml aware editors'' have a menu entry like ''validate'' to run this test though they will likely be missing the path to the docbook directory that holds our custom DTD.  
 
#: '''Tip:''' Some ''xml aware editors'' have a menu entry like ''validate'' to run this test though they will likely be missing the path to the docbook directory that holds our custom DTD.  
−
# Optional: test your work with yelp - there are build system methods to support you:
+
# Other recommended testing and validation options include opening your files in yelp and proofreading in html or pdf format. These extra options require you to generate your translated documentation in the proper formats. How to do so is described in more detail in [[Documentation Update Instructions]]. Please refer to that page for further instructions.
−
## Using a terminal, go to your gnucash-docs directory <SyntaxHighlight lang="sh">
 
−
cd /path/to/gnucash-docs # replace the example path with your real path
 
−
</SyntaxHighlight>
 
−
## Make a build directory next to your source directory and go into it <SyntaxHighlight lang="sh">
 
−
mkdir ../gnucash-docs-build
 
−
cd ../gnucash-docs-build
 
−
</SyntaxHighlight>
 
−
## Configure the build system<SyntaxHighlight lang="sh">
 
−
cmake -D CMAKE_INSTALL_PREFIX=../gnucash-docs-install ../gnucash-docs
 
−
</SyntaxHighlight>
 
−
##: These commands will set up a directory structure as follows:<SyntaxHighlight lang="sh">
 
−
path/to/
 
−
  gnucash-docs/          # directory with gnucash-docs sources
 
−
  gnucash-docs-build/    # directory to generate gnucash-docs in various formats
 
−
  gnucash-docs-install/  # directory to install final result (not needed for development, just for completeness)
 
−
</SyntaxHighlight>
 
−
##: 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.
 
−
## To check your work while editing you can run <SyntaxHighlight lang="sh">
 
−
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 you can add a ''target'' to the command to refers to your work specifically. In this example we will check work on the German version of the guide: <SyntaxHighlight lang="sh">
 
−
make de-gnucash-guide-check
 
−
</SyntaxHighlight>
 
−
##:Note the command always is entered in the top-level of the build directory.
 
−
##: This will run the  <syntaxhighlight lang="sh" inline>
 
−
xmllint</syntaxhighlight> 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 command above with ''pdf'' or ''html'' respectively: <SyntaxHighlight lang="sh">
 
−
make de-gnucash-guide-pdf
 
−
</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-build with the real path to the gnucash-docs build directory you created earlier
 
−
# <docname> with the document you wish to view, either gnucash-help or gnucash-guide
 
−
LANG=<language> XDG_DATA_DIRS=/path/to/gnucash-docs-build/share:${XDG_DATA_DIRS}:/usr/local/share:/usr/share yelp gnome-help:<docname>
 
−
# Example:
 
−
LANG=pt XDG_DATA_DIRS=/path/to/gnucash-docs-build/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 generated document directly via: <SyntaxHighlight lang="sh">
 
−
yelp /path/to/gnucash-docs-build/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.
 
## Repeat these steps until you're satisfied with the result.
 
# Update the branches of your local repo often: <SyntaxHighlight lang="sh">
 
# Update the branches of your local repo often: <SyntaxHighlight lang="sh">

Revision as of 15:20, 20 October 2022

Purpose of this page is to help you to translate [parts of] the official documentation into your language to make it available

  • over the Help menu of the program,
  • for download in several formats as

If you are interested in improving the documentation, you should also read Documentation Improvement.

There are other related pages for

programmers: I18N and
project maintainers: Language Administration.
Note
The instructions below have been adapted for the documentation related to GnuCash 5.0 or more recent. This includes the master branch in git at the time of this writing. If you are looking or instructions to improve older documentation releases, please refer to an older version of this page.

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.
  • Manual, : 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 usable 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 Other 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

  • Cmake and one of
    • Make or
    • Ninja

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
at runtime
yelp (for viewing under linux)
Optional
  • gnome-doc-utils (contains xml2po for the use of po editors like in the it translation)
by target format
Mobipocket
chm (old fashioned Windows Help)
PDF
  • Apache fop >= 0.95
For non-latin scripts
  • Fonts. 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 Cmake 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

Note
The procedure explains what needs to be done to add a new translation to the guide. If you want to add a new translation for the help manual, make the following replacements:
guide manual source directory name
gnucash-guide gnucash-manual document name

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 ${URL} -b maint gnucash-docs
    with ${URL}=https://github.com/Gnucash/gnucash-docs
  2. Create your working branch. If you plan to use pull requests, you should use unique names like LL-guide-chapter-x-part-n instead of working-branch. 
    git checkout -b working-branch
  3. If this is the first gnucash document in your language,
  1. Create a new directory (if it doesn't already exist) as <locale> where <locale> is of the form <language>[_<region>] e.g. es, en_GB, or pt_PT. See #Naming Conventions: 
    mkdir -p ${LOCALE}
  1. 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.
  1. Copy CMakeLists.txt from C into your LL/ directory
  2. Inside CMakeLists.txt adjust the locale string in the first line of this file to match your directory name.
  3. Adjust the following two lines (the ones starting with add_directory). Prepend both with a # sign. That will disable these documents in your language for now. We'll re-enable them as we add the proper document directories later on.
  1. Add an add_directory entry for your language in CMakeLists.txt in the toplevel of your source directory. The format is 
    add_directory(<language>)
    . There are other examples in that file you can follow. Please keep the language list sorted alphabetically.
  2. Copy the guide directory from C (English language) into this directory: 
    cp -r C/guide LL/guide
    For languages that don't use latin characters
    They need additional files to process printing to pdf. See ja or ru as examples.
  3. Notify git about the new directory and files. "*" is quoted by "\". 
    git add LL/CMakeLists.txt LL/guide/\*.\*
    or 
    git add LL/CMakeLists.txt LL/manual/\*.\*
  4. Now the real work:
    1. Edit index.docbook and 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. 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. Obsolete?
    3. In addition to the text, you need to recreate the image files in C/guide/figures so that they are appropriate to your language. For details (size, style,...) see Documentation_Update_Instructions#Screenshots And Other 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.
    4. 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.
  5. Test your xml files for syntax errors by running xmllint on the main file index.docbook, e.g.: 
    cd ${gnucash-docs-dir} # adjust to navigate to your local gnucash-docs source directory
xmllint --postvalid --xinclude --noout --path docbook <LL>/guide/index.docbook # replace <LL> with your language code
    The program xmllint is part of the package libxml.
    Tip: Some xml aware editors have a menu entry like validate to run this test though they will likely be missing the path to the docbook directory that holds our custom DTD.
  6. Other recommended testing and validation options include opening your files in yelp and proofreading in html or pdf format. These extra options require you to generate your translated documentation in the proper formats. How to do so is described in more detail in Documentation Update Instructions. Please refer to that page for further instructions.
    1. Repeat these steps until you're satisfied with the result.
  7. 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
  8. Follow #Submitting your work direct to GnuCash.

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.xm
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
    Remove xx from xx_helpfile.xml and you are ready to commit it in your language help directory

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…

Retrieved from "https://code.gnucash.org/wiki/index.php?title=Documentation_Translation&oldid=21348"