start

# Checking PO files with PO filter

pofilter allows you to check your PO files for certain common error. This quickstart guide takes you through the process of using this tool, making corrections and merging your correction back into your translations.

## Quickstart

1. pofilter -l (select a filter)
2. pofilter -i existing_files/ -o errors/ [-t specific tests] [--excludefilter don’t perform specific tests]
3. vim errors/*.po (delete items you don’t want changed, set fuzzy if needed, delete if not needed)
4. pomerge -i errors/ -o existing_files/ -t existing_files/ (will overwrite existing files)
5. cvs diff -u existing_files/ > x.diff
6. vim x.diff (check to see that the updates are what you want)
7. cvs ci existing_files/

## Detailed Description

pofilter works but running a number of checks against your PO files. Any messages that fail are output to a set of new PO files (in the same structure as the source/parent PO files). You then edit these new PO files to correct any errors. Once you are satisfied with yoru corrections then these are merged into the original PO files using pomerge.

### Extracting Errors

pofilter will run all tests unless you use the -t or --excludefilter options. There are over 30 tests and pofilter can itself provide you with a current list of all the available checks:

    pofilter -l

We want to run the: accelerators, escapes, variables and xmltags tests as these are the ones most likely to break programs at runtime. We are also working with OpenOffice.org PO files created using oo2po so we want to ensure that we set the accelerator key marker and variables definitions correctly.

    pofilter -t accelerators -t escapes -t variables -t xmltags --openoffice existing_files errors

Any messages that fail one of the 4 checks will be placed in PO files in errors. We also used the --openoffice option to ensure that our accelerator marker was to to ~ and that variables types were set accordingly. You can also specify other styles of project including GNOME, KDE or Mozilla.

You can also specify whether you want fuzzy entries included and checked using --fuzzy, by default this is off because fuzzy strings are usually known to be broken and will be reviewed by translators anyway.

Similarly you can include items marked for review --review or --ingnorereview by default review items are included. This is not part of the standard Gettext format we have allowed entries like this when we want to communicate to someone what error we have picked up.

    #, review - wrong word for gallery chosen

This is marked like a fuzzy entry

You can run pofilter without the -t option. This runs all checks at once, this can be confusing if you have a lot of errors as you easily lose focus. One strategy is to run each test individually. This allows you to focus on one problem at a time across a number of files. It is much easier to correct end punctuation on its own then to correct many different types of errors. For a small file it is probably best to run all of the test together.

### Edit the files

Once the errors have been marked you can edit them with any text editor or PO editor eg. KBabel or vi. You will be editing the files in the errors directory. Only messages that failed failed the test will be present. If no message failed then there will be no PO file for the source file. All entries are marked as fuzzy so that you can see your progress in GUI translation tools.

To edit run:

    vi `find errors -name "*.po"`
    kbabel `find errors -name "*.po"`

or similar command.

Pofilter places this style of comment

    #_whitespace: whitespace at the beginning or end of the string did not match

to help you identify what test faile. The format is the name of the test followed by a description of that test.

    #_test: test description

Use the test descripion to help you determine what is wrong with the message. Remember that all your changes will be ported back into the PO files. So if you leave a string fuzzy in the error files it will become fuzzy in the main files when you merge the corrected file back into the main file. Therefore delete anything you do not want to migrate back when you merge the files. Delete the test comments and fuzzy markings as needed.

The computer can get it wrong, so an error that pofilter finds may in fact not be an error. We’d like to hear about these false positives so that we can improve the checks. Also if you have some checks that you have added or ideas for better check then let us know.

### Merging your corrections back into the originals

After correcting the errors in the PO files its time to merge these corrections back into the originals using pomerge.

    pomerge -t existing_files -i errors -o files_without_errors

If -t and -o are the same directory then the corrections will be merged into the existing files. Do this only if you are using some kind of version control system so that you can check the changes made by pomerge.

### Checking the corrections

We have done this against CVS but you could run a normal diff between a good copy and your modifications. Thus we assume in the last step that we merged the corrections into the existing translations:

    pomerge -t existing_files -i errors -o existing_files

Now we check the changes using cvs diff:

    cvs diff -u existing_files > x.diff

This creates a unified diff (one with + and - lines so you can see what was added and what was removed) in the file x.diff

    vim x.diff

Check the diff file in any editor, here we use vim. You should check to see that the changes you requested are going in and that something major did not go wrong. Also look to see if you haven’t left any “#_test: test description” lines which should have been deleted from the error checking PO files. Also check for stray fuzzy markers that shouldn’t have been added. You will have to make corrections in the files in existing_files not in errors.

When you are happy that the changes are correct run:

    cvs ci existing_files

Congratulations you have helped elinate a number of errors that could trip you up when it comes to running the application. Now you might want to look at running some of the other tests that check for style and uniformity in translation.