Difference between revisions of "Documentation Translation"

Revision as of 09:25, 15 August 2023

Purpose of this page is to assist 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.

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 an older version of this page.

Translating the GnuCash Guide and Manual

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 shown by the context sensitive help system and describing the elements of the dialogs.

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

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

chm (old fashioned Windows Help)

• Mingw (http://www.mingw.org)
• Html Help Workshop (https://www.microsoft.com/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 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 manual, make the following replacements:

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

   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_BR. See #Naming Conventions and Locale_Settings#IETF_language_tags:

      LOCALE=LA # Replace Latin by your languages code
      mkdir -p ${LOCALE}
      

      If your translation is the first for your language do not add a region code. So also other regions benefit from your translation.
   2. Copy CMakeLists.txt from C into your ${LOCALE}/ directory
   3. Inside CMakeLists.txt adjust the locale string in the first line of this file to match your directory name.
   4. 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.
   5. Add an add_subdirectory entry for your language in CMakeLists.txt in the toplevel of your source directory. The format is

      add_subdirectory(${LOCALE})
      

      Attention

      Replace ${LOCALE} by its content here.

      There are other examples in that file you can follow.

      Please keep the language list sorted alphabetically.

   6. Copy the guide directory from C (English language) into this directory:

      cp -r C/guide ${LOCALE}/guide
      

      For languages that don't use latin characters

      They need additional files to process printing to pdf. See ja or ru as examples.

   7. Notify git about the new directory and files. "*" is quoted by "\".

      git add ${LOCALE}/CMakeLists.txt ${LOCALE}/guide/\*.\*
      

      or

      git add ${LOCALE}/CMakeLists.txt ${LOCALE}/manual/\*.\*
      

3. 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 {stable|future} branch, commit 1234567 2023-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.

      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 weblate gnucash glossary from the Files menu or
      • the 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 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 docbook/gnc-docbookx.dtd

      Localize the GUI entities

      run Gnucash in your language and adjust the GUI elements in a copy from docbook/gnc-gui-C.dtd into docbook/gnc-gui-${LOCALE}.dtd.

   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.

4. 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 ${LOCALE}/guide/index.docbook
   

   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.

5. 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.
6. Update the branches of your local repo often:

   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
   

7. Follow #Submitting your work direct to GnuCash.

Committers: If it builds fine, add the directory changes from 2. also to gnucash/stable/packaging/win32/install-impl.sh 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: 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 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:

yum install gnome-doc-utils

Other distributions might have split it as a separate [python-]xml2po package.

1. Do the conversion with the following commands (${LL} is your language code, example: el for Greek):

   #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 ../..
   

2. Translate ${LL}.po using your favorite po editor.
3. Convert back to xml:

   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!
   

4. Test your translated xml file as mention above:

   xmllint --valid --noout /${LL}/${COMPONENT}/index.docbook
   

   Now you still have to create the images.

GnuCash Maintainer Tasks

For new languages the core developers have some additional tasks:

New Script

make pdf

First Nightly

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

First Release

Adjust htdocs…