There are two items to check if you finished translating a documentation, namely spelling of the words and syntax of the XML markup.
You could use the spell checker which is built into Lokalize ( → ). This spell checker can be configured through the Regional & Language page of System Settings (Spelling).
To check the XML syntax you have to generate the translated XML documentation (DocBook) from the
POfile. After that you can check the XML syntax of this
docbookfile with an XML parser. You have at least two possibilities to choose from, depending on whether you have only one documentation file or the necessary part of the whole source tree of the documentation for your language:
If you have at least the necessary part (the part where the
POfile in question resides) of the source tree of the package l10n-kf5 for your language and the doc part of the source tree of the package for the translated program (the part where the English
docbookfile in question resides), you could use the script update_xml (part of
l10n-scripty). You also need to have po2xml in your path, as it is called by this script. The script generates the
docbookfiles from the corresponding
POfiles for that language. The script takes the language to compile as first command line parameter, so if your language directory is named
$LANGUAGE, you type
./l10n-scripty/update_xmlto start the script. The script updates all files it can find in your language tree. If you only want to update a certain package or program, you can add it as second parameter to update_xml. For example, to update the German translation package kdemultimedia:
scripts/update_xml de kdemultimedia
or the German translation application JuK:
scripts/update_xml de kdemultimedia juk
update_xml automatically calls the XML checker checkXML5 which makes it validate the generated XML document. If the parsing process fails, it will tell you the line numbers and error messages.
If checkXML5 fails then update_xml will automatically remove the file with errors. That is for safety to ensure that the DocBook files for every language compile. Sometimes this feature prevents you from finding errors, since the error messages print the corresponding line numbers in the
docbookfile and you are not able to check the context because this file is automatically deleted. Therefore the option
was added by Stephan. But keep in mind not to check this file with errors into the SVN tree or else your language will fail to compile until this file is removed or corrected.
If you do not have the above requirements you may call po2xml yourself and generate the
docbookfile. For this to work po2xml needs the English
docbookfile (usually located in the
doc/subdirectory of the package containing the program with the name
index.docbook) and the translated
POfile. The syntax is:
po2xmlThis generates the translated.docbook file.
In the header of the generated file you have to specify your language, i.e. if your language was "German" change the line
<!ENTITY % English "INCLUDE" ><!-- change language only here -->
<!ENTITY % German "INCLUDE" ><!-- change language only here -->
Now that you generated the
docbookfile for your language you can check that the syntax is correct and all used entities (i.e. &kapp; etc.) can be resolved correctly.
It is not enough that the
docbookfile can be displayed more or less correctly by the KDE help center, because the parser there is optimized for speed and does not check the correctness of the XML document. It is very generous in ignoring markup errors and the like.
Instead use the XML parser meinproc5 from Stephan Kulow. The calling syntax is
meinproc5If the parsing process fails it will tell you the line numbers and error messages. You can use this application for generating HTML files, too. Just call
meinproc5and you will find a bunch of HTML files in the current directory. The file
index.htmlis the starting point for browsing the documentation.
Error correction: Keep in mind that you need to correct the errors in the
POfile, because the
docbookfile is autogenerated from this. Start corrections from the beginning of the document, because one error may result in a chain of subsequent errors.
If you get errors about some file "dtd/kdedbx45.dtd" that could not be found, check that the needed version of meinproc5 is called. (If you realize that your self-compiled KDE is missing a new meinproc, check the BZip2 library and recompile kdoctools.)
As for proof-reading: Each language team needs to have a certain procedure for error checking. In the German team for instance we decided on proof-reading the documentation by a different team member because the translator tends to overlook the own spelling errors.
Generating HTML files: The program meinproc5 not only checks the syntax but additionally generates HTML files in the directory of the corresponding
Usually, the coordinator for you language will take care of proof-reading and afterwards committing the translated files to SVN. So please check with him or her about the team policy in this regard.
You should always keep in mind that once your documentation is published on the KDE web server, it will be distributed worldwide and may be read by millions of people. So your translation will substantially influence how users experience KDE.