start

# Inline checking for convertors

We have the ability to run tests on translations as we convert them. For instance converting from PO to OpenOffice.org we can run tests and exclude translations that fail the test. This spec defines the generic behaviour for such inline checkers.

## Core Rules on Behaviour

- We don’t need to emulate behaviour that might already exist in another tool unless it is usefull to the whole l10n process
- Fuzzy tests ie those that are not always 100% correct should not be allowed to drop translations.
- Tests that are 95% correct should be classed in the ‘error’ class and use the override syntax to remove minor false positives.
- Good tests should be able to discard translations
- The convertor selects the tests to run not the user
- A good conversion should pass --check=error with no output.

## Generic Options

- --check=[error|all|discard-error|discard-all] - a generic option added to the convertor requesting that inline checks be run

By default no inline checks will be run and by default if --check is not given an argument then the ‘exclude-error’ level is used. The other error levels are:

- ‘error’ - only check for errors, print a message but don’t discard
- ‘all’ - check for both errors and warnings, print a mess but don’t discard
- ‘discard-error’ - only discard translation that fail an ‘error’ check
- ‘discard-all’ - discard translations that fail an ‘error’ or a ‘warning’ check

## Overridding Checks

Even good tests might have instances where they fail or where programmers have done something strange to create a problem for the test. In this case it should be possible to ignore a test for a certain message block.

Currently we use:

    # (pofilter) variables: blah

To report a failed test. It is proposed that an entry of:

    # (pofilter) -variables

Be use to indicate that the test should be ignored. The colon and description are optional, thus allowing a simple minus sign to be added to override the test. If you wanted to ignore a specific variable you could do:

    # (pofilter) -variables: blah

## Generic Behaviour

There are 3 classes of tests:

1. Error
2. Warn
3. Ignored

### Error

These are errors that could cause problems in compilation and thus you don’t want them in the target files. The translated text is discarded and, depending on the type of target format, the English text is substituted, or the text is left untranslate or the item is left our of the target file.

This test will print the following message:

    Error: %file% %message% %error%

### Warn

These are non-fatal errors that can be included in the text but should be corrected. In this case the warning is printed and the translated text is used as normal

This test will print the following message:

    Warning: %file% %message% %error%

### Ignored

This is not a real test class but is a simple grouping of all tests that are not used during the inline checking.

## Overiding pofilter behaviour

As pofilter is used mostly by humans and as we want machines to do this checking we need to be able to override the generic definitions defined in pofilter. For instance pofilter --openoffice defines a number of variable styles for OpenOffice.org, some of which produce mostly false positives.

It must be possible allow the convertor to define the variables check in different classes so that you can run variable checks at the ‘error’ level when you are 100% sure of these type of variables. But also include the same test in the ‘warn’ level so that you can also test variables that produce too many false positives.