PrevDoc TranslationNext

Checking and Committing Your Work

Checking the Markup and the Spelling

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 (Tools → Spelling...). 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 PO file. After that you can check the XML syntax of this docbook file 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 PO file 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 docbook file 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 docbook files from the corresponding PO files 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_xml $LANGUAGE to 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.

      Note

      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 docbook file and you are not able to check the context because this file is automatically deleted. Therefore the option --nodelete 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 docbook file. For this to work po2xml needs the English docbook file (usually located in the doc/ subdirectory of the package containing the program with the name index.docbook) and the translated PO file. The syntax is: po2xml english.docbook translated.po >translated.docbook This 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 -->

      like this: 

      <!ENTITY % German "INCLUDE"  ><!-- change language only here -->

      Now that you generated the docbook file for your language you can check that the syntax is correct and all used entities (i.e. &kapp; etc.) can be resolved correctly.

      Important

      It is not enough that the docbook file 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 meinproc5 --check translated.docbook If 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 meinproc5 translated.docbook and you will find a bunch of HTML files in the current directory. The file index.html is the starting point for browsing the documentation.

  • Error correction: Keep in mind that you need to correct the errors in the PO file, because the docbook file 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.

Note

Generating HTML files: The program meinproc5 not only checks the syntax but additionally generates HTML files in the directory of the corresponding docbook file.

What to Do with Translated and Corrected Documentation?

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.