Checking and Committing Your Work

Please, never commit a PO file to the SVN source tree without at least validating its syntax. Please also do the other checks described in this section. And do not forget about your spell checker.

Syntax Check: msgfmt --statistics --check-header

msgfmt --statistics --check-header /path/to/translated/files is the absolute minimum check you have to do on every file that you are about to send to your coordinator or to commit directly to SVN. What it does is give you either the number of (un)translated strings or the location and the nature of any formatting errors in your translated files. "msgfmt" (in case you are wondering) is part of the GNU gettext package.

Some specialized programs like Lokalize will assist you with this. Lokalize even contains an automated syntax check (among others) that saves you a lot of the work.

There are also nightly script (nicknamed Scripty) will run on the i18n server and also check the PO files. For wrong PO files, the script will tried to mark wrong entries as fuzzy, but it cannot report in the PO file more serious errors. Such errors are only reported to Scripty's log, which is publicly available. (The files are named like yymmdd.log where yy is the 2 digit year, mm the 2 digit month and dd the 2 digit day. As the logs are packed with full of information, a tip is to try to search all occurrences of your language code to get the corresponding errors.) You can spare yourself a lot of administrative work if you keep this from happening. And you can do this quite easy — you guessed it — by testing all your PO files yourself before committing them.

Checking for Missing Variables and Other Problems

Apart from syntax checks you also have to ensure that there are no problems in the following areas:

  • Context information: As pointed out before, PO files may contain comments on the exact meaning of a string (e.g. if "home" stands for the user directory, a key on the keyboard or the beginning of a line). This context information must not show up in your translation.

  • Arguments: Many strings show variables (%1, %2, %3...) which will be replaced with actual contents on runtime of the program. The variables of the original string must all show up in the translation (although not necessarily in the same order).

  • Equations: have to be balanced in the translation just the same as in the original.

Again, Lokalize provides automatic validation routines for all these possible issues. In recent versions, it also allows spell checking of your files.

Moreover, you cannot commit broken files using kdesvn: system just shows you the same error messages as msgfmt --statistics --check-header.

XMLSyntax Check

Another major issue that can be found in translations is XML syntax violation. These issues cause wrong formatting of messages and even crashes of translated programs. To reveal this kind of issues you can use Pology. Please follow these instructions:

  1. Run Lokalize (better with proper project opened)

  2. Ensure python and python-dbus is installed

  3. Run the following commands in konsole:

    KDESVN=/home/your_account/hacking/kde/trunk/
    KDESVNLANG=your_language_code
    svn up $KDESVN/l10n-support/pology/
    cd $KDESVN/l10n-kf5/$KDESVNLANG
    $KDESVN/l10n-support/pology/scripts/posieve.py check-xml-kde4 -s lokalize messages
    

    of course you should adjust vars to your situation, and instead of running the check against whole messages/, you may want to specify e.g. messages/kdepim.

After the last command Pology will open in Lokalize erroneous files and show feedback on errors in console output.

(Most info in this section thanks to Nick Shaforostoff.)

Compilation, Context and Accelerator Checks

To be able to check the translated packages in the context of the program interface, you have to generate the "(G)MO" files we mentioned above. This is accomplished by compiling the sub-folder of the l10n package appropriate to the translated language:

Change to the directory l10n-kf5 and compile the files with ./scripts/autogen.sh $LANGUAGE && cd $LANGUAGE && mkdir build && cd build && cmake .. && make (where $LANGUAGE is the language code)

In case there are any error you may want to try cmake .. && make -k; make -k docs; make -k install. With the -k parameter files and directories that do not compile are skipped. For more on this subject, see the info in the HOWTO section.

After su -c "make install" it should be possible to choose your language and to see your translation in the program interface (assuming you compiled the program also). Now you can start your context checks: Go through all menus and dialogs and check if all your translations make sense in their real environment. Make ready for some big surprises. Then correct your PO file, recompile and check again.

If you think that the mistakes in interface translation are due to the lack of context information in translation files, you should mail kde-i18n-doc mailing list so that authors or other competent persons add proper context and this doesn't happen to others.

These context checks are often neglected due to tight release schedules. But everybody who has seen how unprofessional and even ridiculous a whole program can look if it has a lot of out-of-context information in its menus will agree that these checks are among the most important things in the whole translation process.

Another test that can only be done after the translated program has been compiled is the check for "accelerator clashes".

As pointed out earlier, the "&" character in PO files is used to mark "accelerator keys" (a letter which in combination with Alt (on PC keyboards) will execute a command). Program authors and translators have to make sure that no accelerator key shows up twice in the same menu (e.g. that there is not something like "&Save" and "&Save as" but maybe "&Save" and "Save &as" ). In other words: you have to prevent "accelerator clashes".

Committing Your Work to SVN

After having checked their work, most translators will sent their completed translations to their language coordinator. The coordinator will usually check again and then commit their files to the main SVN server at svn.kde.org.

The necessary information on SVN and its graphical frontends is given in the section Taking a Look at Available Resources and SVN, including some hints about the commands and parameters needed.

Note

You cannot commit a file if the SVN server has a more recent revision of the same file. In that case, you will probably need to use svn update to get the new version. SVN will merge it for you. You should check the result, as SVN merges only text files; it has not any idea about the syntax of a PO file. In some cases, you will get conflict, which you will need to fix (technically this is called "resolve").

SVN Conflicts

One thing to watch out for are version conflicts. When you update files by SVN, SVN will try to merge changes, if there are changes on both your local version of a file and the version of the SVN server of that file. SVN only merges text lines and this works normally well. But not always...

One kind of problems could be that the resulting file is not a valid PO file, as SVN has not any idea about the syntax of PO files, as for SVN, PO files are just a text files.

Another, more serious kind of problems is called a conflict. In that case, SVN gives up the merging, telling that it could not merge, as both the local change and the change of the server are on the same lines of a file. SVN remember that a conflict has happened and will refuse to commit the file until you have told SVN that the conflict was fixed.

In case of conflicts in text files, SVN tries to be helpful and puts special marks (lines with <, = and > characters) to help the user to see what are the conflicting change. It is your task as user to resolve (i.e. fix) the conflict. In the case of binary files, SVN cannot offer such a service, to avoid to corrupt the file.

For example:

# translation of granatier.po to Ukrainian
# Copyright (C) 2008-2009 This_file_is_part_of_KDE
# This file is distributed under the same license as the Granatier package.
#
# Yuri Chornoivan <yurchor@ukr.net>, 2008, 2009.
msgid ""
msgstr ""
"Project-Id-Version: granatier\n"
"Report-Msgid-Bugs-To: http://bugs.kde.org\n"
<<<<<<< .mine
"POT-Creation-Date: 2009-09-27 06:24+0200\n"
"PO-Revision-Date: 2009-09-27 10:00+0300\n"
=======
"POT-Creation-Date: 2009-09-27 06:24+0200\n"
"PO-Revision-Date: 2009-09-24 17:30+0300\n"
>>>>>>> .r1028458
"Last-Translator: Yuri Chornoivan <someaddress@ukr.net>\n"
"Language-Team: Ukrainian <nowhere@linux.org.ua>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && "
"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n"
"X-Generator: Lokalize 0.3\n"

<<<<<<< .mine
#. i18n: file: generalsettings.ui:30
#. i18n: ectx: property (text), widget (QLabel, label_3)
#: rc.cpp:21 rc.cpp:89
msgid "Round Time in Seconds"
msgstr "Тривалість раунду у секундах"

#. i18n: file: generalsettings.ui:70
=======
#. i18n: file: generalsettings.ui:30
#. i18n: ectx: property (text), widget (QLabel, label_3)
#: rc.cpp:21 rc.cpp:89
msgid "Round Time in Seconds"
msgstr ""

#. i18n: file: generalsettings.ui:70
>>>>>>> .r1028458
#. i18n: ectx: property (text), widget (QLabel, label_2)
#: rc.cpp:24 rc.cpp:92
msgid "Points to win the game"
msgstr "Кількість очок, потрібна для виграшу"

Probably you wonder now how to solve such a problem. Normally you can try to solve it by using your normal tool, e.g. Lokalize. But sometimes, this is not possible and you need to use a text editor, e.g. Kate. An easy way of removing a conflict is to revert the file by the command svn revert. Another is to use one of the auxiliary files created by the update with have file names starting by the file name of the conflicting file. You can simply copy the version that you find correct instead of the file with a conflict.

When you have fixed the conflict, you need to tell SVN that you have fixed the conflict, so that SVN will allow you to commit the file. This can be done easily by svn resolved. (If you have chosen to revert the file, this step is not necessary, as SVN has already done it implicitly.)

Note

Conflicts might appear often with PO files automatically merged by Scripty. Here a good solution is to keep working on the local version (so copy the corresponding file (.mine) over). Scripty will again work during the next European night and morning. But if you cannot wait you can do manual merge with templates. Just use the command ../scripts/merge_all.sh from your l10n-kf5/$LANGUAGE directory.