Checking and Committing Your Work
Prev
Next

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 KBabel will assist you with this. KBabel even contains an automated syntax check (among others) that saves you a lot of the work.

The 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 occurences 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, KBabel provides automatic validation routines for all these possible issues. In recent versions, it also allows spell checking of your files.

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" and create a file named inst-apps and add the language(s) that you want to compile (one per line, see the subdirs file as example of the needed format.)

  • Then just compile with ./scripts/autogen.sh && ./configure && make && make install.

Note

If you need only just one language, you do not need to create an inst-apps file but you can use the language code as parameter of autogen.sh, like (where xx is the language code) ./scripts/autogen.sh xx && ./configure && make && make install

Tip

If you are using unsermake instead of automake, then replace make by unsermake, so the full command becomes: ./scripts/autogen.sh && ./configure && unsermake && unsermake install

In case there are any error you may want to try ./configure & & 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 this 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.

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:

Date:    Wed, 05 Jan 2000 15:33:17 +0100
From:    Stephan Kulow <coolo@kde.org>
To:      kde-i18n-doc@master.kde.org
Subject: Re: Errors?

Marko Rosic wrote:
> > msgid ""
> msgstr ""
> <<<<< kdelibs.po
> "Project-Id-Version: PACKAGE VERSION\n"
> "POT-Creation-Date: 1999-12-06 00:59+0100\n"
> "PO-Revision-Date: 1999-12-30 20:22+0100\n"
> "Last-Translator: Strahinja Radi <E6> <rstraxy@sezampro.yu>\n"
> "Language-Team: Serbian <LL@kde.org.yu>\n"
> =======
> "Project-Id-Version: kdelibs\n"
> "POT-Creation-Date: 1999-12-30 00:53+0100\n"
> "PO-Revision-Date: 1999-08-23 12:57+0100\n"
> "Last-Translator: Marko Rocic <roske@mainstream.co.yu>\n"
> "Language-Team: Serbian <sr@li.org>\n"
> >>>>>>> 1.21
> "MIME-Version: 1.0\n"
> "Content-Type: text/plain; charset=iso-8859-2\n"
> "Content-Transfer-Encoding: ENCODING\n"
> > What does this mean? Which do I need to delete?
Depends. The portion between <<<<< and ====="=" is your version
and the one between ===="=" and >>>>>> is the one in CVS. I would
say merge them :)

Greetings, Stephan

Note

The example above come from the time KDE used CVS and is embeded in an email. But it could happen with SVN too, in a very similar way.

Probably you wonder now how to solve such a problem. Normally you can try to solve it by using your normal tool, e.g. KBabel. 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 over). (Scripty will again work during the next European night and morning.)

Prev
Next
Home