Help:Extension:Translate/Validators

Translatable strings often contain markup that should be retained as-is in the translation. Typing that markup can be slow and difficult because special characters are common. Translate extension can provide translators a button clicking on which inserts the piece of markup into the translation to the current cursor position. In addition, if a translation is missing that specific markup, the Translate extension can either warn the translator or simply reject the translation, since such markup is usually mandatory to display the messages properly to the end user.

For example in the string,"Adapted by %{name} from a work by %{original}"There are two insertables -  and. If the translator does not add them to their translation, the end user using the software will not see a proper message.

The  framework has been added with the intent of helping with validating translations. Validators run on the translated message and based on the configuration, a warning or error message is shown to the translator. Translations with warnings can still be saved, but ones that have error cannot. Only a user with  permission can save translations that have errors.

When configuring a validator, a regex is defined to identify markup that is mandatory. The validator can also be marked as insertable, in which case a button will be displayed to the translator to add that markup into the translation.

Adding a custom validators is still possible and will be needed for more specialized validations.

Configuration
Following is a summarized validator configuration,

In the example above,


 * 1)   is a bundled validator that can accept a custom regex and run validations.
 * 2)   is a custom validator class.
 * 3)   is another bundled validator.

uses an array format. Lets look at the various parameters being used here in each array item,

Pre-provided / Bundled validators
Following is a list of bundled validators,

BraceBalance
ID:

Ensures that the number of open braces / brackets, matches the number of closed braces / brackets in the translation.

For example, the following translations would pass,



whereas, the following would fail,



This validator cannot be marked as insertable.

EscapeCharacter
ID:

The validator ensures that only the specified escape character are present in a translation.

The allowed escape characters can be specified when adding the validator, and can only include,



This validator is not insertable.

GettextNewline
ID:

This works specifically for GetText based message groups.

Ensures that the translation has the same number of newlines as the source message at the beginning and end of the string.

GettextPlural
ID:

This works specifically on GetText based message groups.

Ensures that if the source / definition contains a plural in the format -, the translation must contain it as well. Based on the language this also checks if the translation has the correct number of plural forms. For example, English has two, but Hebrew has four.

InsertableRegex
ID:

A generic reusable validator that can be used to specify custom validations and insertables.

For example, take the following configuration where the validator is marked as insertable and enforced,

Given the following source message - ''Hello $name. My name is $myName. that is being translated, the translation must have the parameters - $name and $myName''. They will also be displayed as insertables to make it easier for translators to use them in the translation. An absence of these parameters will cause an error to be displayed to the translator.

InsertableRubyVariable
ID:

This is a validator that matches ruby variables in the translations. Internally it extends  and uses the following regex -. This validator is insertable.

Example:.

MatchSet
ID:

Ensures that the translation is present in the list of values. Also takes a parameter -  that can be either true (default) or false.

For example the following configuration, the validator will validate the message with key -  and ensure that the values for it can either be ltr or rtl. Note that LTR or RTL will not be valid values, since  is true by default.

MediaWikiMisc
ID:

Provides validations for expiry options and IP block options specified in the MediaWiki core. These are usually in the format, The validations ensure that the translations have the exact same number of key-value pairs. These validations are run only on messages with keys,


 * 1) protect-expiry-options
 * 2) ipboptions

MediaWikiPlural
ID:

Ensures that if the source / definition contains a, the translation should also have it. It can also be used as an insertable. Based on the language this also checks if the translation has the correct number of plural forms. For example, English has two, but Hebrew has three.

Newline
ID:

Ensures that the translation has the same number of newlines as the source / definition message at the beginning of the string. This validator is not insertable.

Printf
ID:

This validator checks for missing and unknown printf formatting characters in translations. This validator is insertable.

Example:,   etc.

SmartFormatPlural
ID:

This works specifically on SmartFormat based message groups.

Ensures that if the source / definition contains a plural in the format -, the translation must contain it as well. Based on the language this also checks if the translation has the correct number of plural forms. For example, English has two, but Hebrew has four.

UnicodePlural
ID:

Ensures that if the source / definition contains a plural in the format -, the translation must contain it as well. Based on the language this also checks if the translation has the correct number of plural forms. For example, English has two, but Hebrew has three.

WikiParameter
This is a validator that matches wiki parameters in the translations. Internally it extends  and uses the following regex -. This validator is insertable.

Example:,.

User interface
The user interface has been updated to differentiate between errors and warnings.

During translation, if an error is noticed with the translation, the Save translation button is disabled unless the user who is translating has  permission.

Additionally validation is also done on the server when the user is saving the translation. This will still allow users who have the  permission to save the translation even if it has errors.

Custom validators
Certain complicated validations might still require a custom validator to be written. Custom validators must implement the  interface. They can use the trait   that contains some commonly used methods. Below is an example of a custom validator, The format for the  array,