View source for Documentation Translation

[[Category:Translation]]
[[Category:Documentation Development]]
Purpose of this page is to assist you to translate [parts of] the official documentation into your language to make it available
* over the <tt>Help</tt> menu of the program,
* for download in several formats as
**[{{URL:www}}docs.phtml released version] or
**[{{URL:Build}}docs/ nightly snapshot].

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. 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 Manual and Guide==
This section describes the actions needed to translate the manuals. There are currently 2 parts:
* '''Manual''': This is shown by the context sensitive help system and describing the elements of the dialogs.
* ''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. 

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 [{{URL:wp}}DocBook 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 [{{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 Other 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 [{{URL:dbk-tdg}}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.

You can check the [{{URL:Build}}docs/ 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 [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/README 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 <tt>xml2po</tt> for the use of po editors like in the it translation)

:;by target format:
::; Mobipocket:
:::* Calibre (https://www.calibre-ebook.com/)

::;chm (old fashioned Windows Help):
:::* Mingw (http://www.mingw.org)
:::* Html Help Workshop ({{URL:MS}}en-us/download/details.aspx?id=21138 for Win XP - 8)

::;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 [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/README 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
----

===== {{Mac}} =====
At present we do not know of a suitable DocBook file toolset for ''{{Mac}}'' 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. --[[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
: [Wm: 
::* I wonder how many current *nix users have it?
::: AFAIK it is still part of the GNOME desktop: [https://www.google.de/search?q=yelp+gnome google search for yelp+gnome] --[[User:Fell|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. --[[User:Fell|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 manual, make the following replacements:
{| class="wikitable" style="text-align: center;"
! scope="col"|Place
! colspan="2"|Component
|-
! scope="row"|source directory name
|guide
|manual
|-
! scope="row"|document name
|gnucash-guide
|gnucash-manual
|}
First, you have to download the most recent version of the gnucash-docs package. This is done as follows:
# Checkout the documentation in a directory ''gnucash-docs'':
#: <syntaxhighlight lang="sh">git clone ${URL} -b stable 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 ''LL-guide-chapter-x-part-n'' instead of working-branch.
#: <syntaxhighlight lang="sh">git checkout -b working-branch</syntaxhighlight>
#;If this is the first GnuCash document in your language:
## 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_BR. See [[#Naming Conventions]] and [[Locale_Settings#IETF_language_tags]]: <syntaxhighlight lang="sh">
LOCALE=LA # Replace Latin by your languages code
mkdir -p ${LOCALE}
</syntaxhighlight> If your translation is the first for your language ''do not append a region code''. So also other regions benefit from your translation.
## Copy C/CMakeLists.txt into your ${LOCALE}/ directory and inside ${LOCALE}/CMakeLists.txt
### adjust the locale string in the first line of this file to match your directory name;
### 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.
## In '''CMakeLists.txt''' in the ''toplevel'' of your source directory add an ''add_subdirectory'' entry for your language. The format is <syntaxhighlight lang="cmake">
add_subdirectory(${LOCALE})</syntaxhighlight>
##;Attention: Replace <q>${LOCALE}</q> by its content here.
##:There are other examples in that file you can follow.
##:Please keep the language list sorted alphabetically.
##Create a localized dtd
##: It should primary contain the localization of the program's GUI elements like menu entries and is used in many places. 
###<syntaxhighlight lang="sh">cp dokbook/gnc-gui-C.dtd dokbook/gnc-gui-${LOCALE}.dtd</syntaxhighlight>
###Localize its content. Example: The first enry is [{{URL:GH}}Gnucash/gnucash-docs/blob/e53a0bfd60d87d0150a8dfaf4f1aad3b67fa5ada/docbook/gnc-gui-C.dtd#L25-L26 docbook/gnc-gui-C.dtd#L25-L26] <syntaxhighlight lang="xml">
<!-- File-Menu -->
<!ENTITY % gm.file "<guimenu><accel>F</accel>ile</guimenu>">
</syntaxhighlight> Replace Docbooks <code><accel>F</accel></code> by Gnomes gettext convention <code>_F</code> and search in the '''program''''s po file of your language for the string <code>"_File"</code> i.e. [{{URL:GH}}Gnucash/gnucash/blob/16c9957cac7b2ca2fe4b2b4a25c92878fcd4067b/po/zh_CN.po#L27145-L27147 zh_CN.po#L27145-L27147] <syntaxhighlight lang="po">
#: gnucash/ui/gnc-main-window.ui:8
msgid "_File"
msgstr "文件(_F)"
</syntaxhighlight> Convert the msgstring in the other direction and store <code>文件(<accel>F</accel>)</code> as  value of gm.file in gnc-gui-zh.dtd. You can fasten that by using <syntaxhighlight lang="console">$ msggrep --msgid -e '_File' po/zh_CN.po
# GnuCash PO file, for Simplified Chinese.
[–]

#: gnucash/gtkbuilder/dialog-doclink.glade:276
msgid "Linked _File"
msgstr "本地文件(_F)"

#: gnucash/ui/gnc-main-window.ui:8
msgid "_File"
msgstr "文件(_F)"

#: gnucash/ui/gnc-plugin-basic-commands.ui:6
msgid "New _File"
msgstr "新建(_F)"

</syntaxhighlight> in you programs top source directory. Continue with the next entry …
##:Perhaps someone would provide a script?
## Copy the guide directory from C (English language) into this directory: <syntaxhighlight lang="sh">cp -r C/guide ${LOCALE}/guide</syntaxhighlight>
##:;For languages that don't use latin characters: They need additional files to process printing to pdf. See <tt>ja</tt>, <tt>ru</tt>, or <tt>zh</tt> as examples.
## Tell your documents to use your localized dtd: <syntaxhighlight lang="sh>
cd ${LOCALE}/guide
for i in *.dokbook; do sed -i "s/gnc-gui-C.dtd/gnc-gui-${LOCALE}.dtd/" $i; done
for i in *.xml; do sed -i "s/gnc-gui-C.dtd/gnc-gui-${LOCALE}.dtd/" $i; done
cd ../..</syntaxhighlight>
## Notify git about the new directory and files. "*" is quoted by "\".
##: <syntaxhighlight lang="sh>git add ${LOCALE}/CMakeLists.txt ${LOCALE}/guide/\*.\*</syntaxhighlight> or <syntaxhighlight lang="sh>git add ${LOCALE}/CMakeLists.txt ${LOCALE}/manual/\*.\*</syntaxhighlight>
# Now the real work: 
## 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:
##: <syntaxhighlight lang="xml"><!-- Translation based on {stable|future} branch, commit 1234567 2023-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 consistent terminology:
##:;Program's Glossary: If you did not [[Translation#Get_the_source_from_Git]], you can simply download your languages .po file from
##::* after selection in [{{URL:wl}}glossary/ weblate gnucash glossary] from the <tt>Files</tt> menu or
##::* the [{{URL:GH}}Gnucash/gnucash/tree/stable/po/glossary glossary directory at GitHub].
##::Verify its completeness and ''use its content in your translation''. If it is not complete, update it according [[Translation#The_glossary_file]].
##:;Guide's Glossary: Verify that you have a recent version of [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/C/guide/gnc-glossary.xml C/guide/gnc-glossary.xml] in your languages subtree and ''translate it''—also for your later use.
##;Use existing entities: See [[Documentation_Improvement#Conventions]]
##:;Familiarize yourself with the global entities: They are defined in [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/docbook/gnc-docbookx.dtd docbook/gnc-docbookx.dtd]
##:;Localize the GUI entities: run Gnucash in your language and adjust the GUI elements in a copy from [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/docbook/gnc-gui-C.dtd docbook/gnc-gui-C.dtd] into docbook/gnc-gui-${LOCALE}.dtd.
## <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 '''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.
### 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]]. 
# Test your xml files for syntax errors by running ''xmllint'' on the '''main file''' ''index.docbook'', e.g.:
#: <Syntaxhighlight lang="sh">
cd ${gnucash-docs-dir} # adjust to navigate to your local gnucash-docs source directory
xmllint --postvalid --xinclude --noout --path docbook ${LOCALE}/guide/index.docbook
</Syntaxhighlight>
#: 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. 
# 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.
## Repeat these steps until you're satisfied with the result.
# Update the branches of your local repo often: <SyntaxHighlight lang="sh">
git checkout stable              # switch to the stable branch
git pull --rebase                # update it
git rebase stable working-branch # update working-branch
git checkout working-branch      # switch back to working-branch
</SyntaxHighlight>
# Follow [[#Submitting your work direct to GnuCash]].

'''Committers:''' If it builds fine, add the directory changes from 2. also to <tt>gnucash/stable/packaging/win32/install-impl.sh</tt> and merge the change to future, if it exists and they are required there.

=== DocBook xml editors ===
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 [[{{URL:wp-de}}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.

=== 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 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 documentation.

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

:;Prerequisite: First you have to install a fresh version of '''gnome-doc-utils'''. For example in a Fedora 13 system: <syntaxhighlight lang="sh">
yum install gnome-doc-utils
</syntaxhighlight> Other distributions might have split it as a separate <tt>[python-]xml2po</tt> package.

#Do the conversion with the following commands (${LL} is your language code, example: el for Greek): <syntaxhighlight lang="sh">
#Append your language code
LL=
# and the desired component {manual|guide}
COMPONENT=
# Create pot
## cd to get short references: 
cd C/${COMPONENT}
## (it seems to reverse the order)
## if already translated xml files exist, specify them with -r
xml2po -k -o ../../${COMPONENT}.pot *.xml index.docbook
cd ../..
# Create target directories
mkdir -p ${LL}/${COMPONENT}/figures
cp C/${COMPONENT}/CMakeLists.txt ${LL}/${COMPONENT}/
cd ${LL}/${COMPONENT}
# Create po
## If on behalf of others, append --no-translator
msginit -l$LL -i../../${COMPONENT}.pot
cd ../..
</syntaxhighlight>
#Translate ${LL}.po using your favorite po editor.
#Convert back to xml: <syntaxhighlight lang="sh">
cd C/${COMPONENT}
  xml2po -p ../../${LL}/${COMPONENT}/${LL}.po -o ../../${LL}/${COMPONENT}/index.docbook index.docbook
for i in *.xml; do
  xml2po -p ../../${LL}/${COMPONENT}/${LL}.po -o ../../${LL}/${COMPONENT}/$i $i;
done
cd ../..//${LL}/${COMPONENT}
echo Do not add ${COMPONENT}.pot into git!
</syntaxhighlight>
#Test your translated xml file as mention above: <syntaxhighlight lang="sh">
xmllint --valid --noout /${LL}/${COMPONENT}/index.docbook
</syntaxhighlight> Now you still have to create the images.

=== GnuCash Maintainer Tasks ===
For new languages the core developers have some additional tasks:

==== New Script ====
Check <syntaxhighlight lang="sh">make pdf</syntaxhighlight> Do we need additional TTFs?

==== First Nightly ====
Ask the admin of {{BuildServer}} to create the new directory.

==== First Release ====
Adjust htdocs…