Koha Manual

Koha Manuals - the differences

The newer manuals form 17.05 on are using Sphinx, the older ones were done using DocBook. As the older manuals are still in use, you can still find instructions on how to generate them on this page, but active work should concentrate on the newer Sphinx versions.

This page is for the more technical stuff - if you want to help out, please see: Editing the Koha Manual

Sphinx based manual

Please check the Readme on gitlab for instructions on how to generate and work with the manuals locally.

DocBook based manual

Localization

To make KOHA manuals available in other languages, and not just in English, we can use the standard way for translating DocBook documents using a tool called ITS tool, enabling us to generate POT and PO files for translating other languages and then generate a translated XML (DocBook) in other languages.

ITStool and XML2PO

ITS Tool allows you to translate your XML documents with PO files, using rules from the W3C Internationalization Tag Set (ITS) to determine what to translate and how to separate it into PO file messages.

XML2PO

xml2po is a simple Python program which extracts translatable content from free-form XML documents and outputs gettext compatible POT files. Translated PO files can be turned into XML output again

more information

The Procedure to Localize the manual (Technical Side)

Make the "manual.xml" translatable

First we need to make the "manual.xml"(which is DocBook file) translatable:
A .pot file is generated from DocBook XML file by running:

xml2po -e -o manual.pot manual.xml

then manual.pot will be generated. we used here the xml2po with the option -e to expand entities xml2po is better in this side than itstool so just in this step we will use it.

Generating the po files for each language

by open the pot with some po editor and save it as LANG.po
or by duplicate the pot file and rename it as LANG.po

Generating the translated manual.xml

After the completion of the translation process, a translated XML DocBook is generated from .po file, and the original English DocBook. For this we have first to use msgfmt to generate mo file by running eg:

msgfmt fr.po

then a messages.mo will be generated. Using this mo file we can generate the xml file by running :

itstool -m messages.mo -o fr/ manual.xml

Then the translated docbook will be generated in the sub-folder /fr

Keeping the translated manual updated

After original DocBook (the English Version) is updated, a merging mechanism allow to update .pot file and .po files, so the translator may just translate the new stings easily.

Generate a new .pot file (for the new version of the xml), and update the po files from the new .pot file by running:

 msgmerge -U fr.po manual.pot

where :

manual.pot is the new generated .pot file
and the fr.po is the translated po file in the previous version

For translators

You have to leave all the XML tags and any strange symbols, and translate only the text.

About Images

I suggest that each group make screenshots for the Koha interface in their language and place them in the folder /images in the same sub-folder and in the same name, so that it will make the manual text and images in <YOUR LANGUAGE> .