Difference between revisions of "Documentation Translation"

Revision as of 19:20, 30 December 2021

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
- [[[:Template:WebURL]]/docs.phtml released version] or
- 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.

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, old name: Help: This is the context sensitive help system. The renaming is in progress. The sources already use manual, but the installed document is still gnucash-help.

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

Calibre (https://www.calibre-ebook.com/)

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)

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 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-help	document name

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:
```
git clone ${URL} -b maint gnucash-docs
```
with ${URL}=https://github.com/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.
```
git checkout -b working-branch
```
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:
```
mkdir -p ${COMPONENT}/${LOCALE}
```
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 additional files to process printing to pdf. See ja or ru as examples.
Add an entry for your directory in [guide/]CMakeLists.txt. The format is
```
add_directory(<language>)
```
. There are other examples in those files you can follow. Please keep the language list sorted alphabetically.
Notify git about the new directory and files. "*" is quoted by "\".
```
git add guide/$LL/\*.\*
```
or
```
git add manual/$LL/\*.\*
```
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:
  
  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.
  - 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 glossary directory at GitHub.
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 guide/C/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.
Test your xml files for syntax errors by running xmllint on the main file gnucash-{guide|help}.xml, e.g.:
```
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
```
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.
Optional: test your work with yelp - there are build system methods to support you:
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 next to your source directory and go into it
```
mkdir ../gnucash-docs-build
cd ../gnucash-docs-build
```
3. Configure the build system
```
cmake -D CMAKE_INSTALL_PREFIX=../gnucash-docs-install ../gnucash-docs
```
  These commands will set up a directory structure as follows:
  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)
  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 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:
```
make de-gnucash-guide-check
```
  Note the command always is entered in the top-level of the build directory.
  
  This will run the xmllint command above over the full directory structure.
3. 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:
```
make de-gnucash-guide-pdf
```
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-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
```
  This uses yelp's built-in mechanism to select the proper language.
5. Alternatively you can open the generated document directly via:
```
yelp /path/to/gnucash-docs-build/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.

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

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

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
```
Translate helpfile.xml.xx.po using your favorite po editor.

Convert back to xml:

xml2po -e -p helpfile.xml.xx.po -o xx_helpfile.xml helpfile.xml

Test your translated xml file as mention above:
```
xmllint --valid --noout xx.helpfile.xml
```
Remove xx from xx_helpfile.xml and you are ready to commit it in your language help directory

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…

@@ Line 11: / Line 11: @@
 There are other related pages for
 :programmers: [[I18N]] and
-:project maintainers: [[Language_Administration]].
+:project maintainers: [[Language Administration]].
 == Translating the GnuCash Guide and Help==

Difference between revisions of "Documentation Translation"

Revision as of 19:20, 30 December 2021

Contents

Translating the GnuCash Guide and Help

Prerequisites

Linux

Other Operating Systems

macOS

Windows

Java (all OS)

The Procedure

DocBook xml editors

Using po editors

GnuCash Maintainer Tasks

New Script

First Nightly

First Release

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Related Sites

Contributing

Tools