grunt-banana-checker

banana-checker

Checker for the 'Banana' JSON-file format for interface messages, as used by MediaWiki and jQuery.i18n.

By default, Banana checker asserts the following:

• The source and documentation files must exist and contain valid JSON.
• Both files include a @metadata object.
• Each defined source message is documented.
• Each defined documentation entry has a matching source message.

For all available options, see the Options section.

You can use Banana checker standalone or as a Grunt plugin.

Getting started (Grunt plugin)

To use this plugin, add it as a development dependency to your project:

npm install grunt-banana-checker --save-dev

Ensure your project has a Gruntfile.js file (example file). Then, in Gruntfile.js, add the line:

grunt.loadNpmTasks( 'grunt-banana-checker' );

Configure the Grunt plugin

In Gruntfile.js, add a configuration key for banana and set it to an empty object.

We will use this object to declare which directory contains the interface messages. For example, to enable grunt-banana-checker for a single directory only, configure it like so:

grunt.initConfig( {
	banana: {
	    all: 'i18n/'
	}
} );

You can also configure multiple directories, like so:

grunt.initConfig( {
	banana: {
	    core: 'languages/i18n/',
	    installer: 'includes/installer/i18n/'
	}
} );

You can also use globbing patterns and/or arrays of directories, like so:

grunt.initConfig( {
	banana: {
	    all: 'modules/ve-{mw,wmf}/i18n/'
	}
} );

For a full list of supported ways of defining the target directory of a Grunt plugin, see Configuring tasks on gruntjs.com.

To customise the options for Banana checker, define your target directory as an object instead of a string, with src and options properties, like so:

grunt.initConfig( {
	banana: {
		all: {
			src: 'i18n/',
			options: {
				sourceFile: 'messages.json',
				documentationFile: 'documentation.json'
			}
		}
	}
} );

For all available options, see the Options section.

Command-line

The Banana checker also offers a command-line interface.

npm install grunt-banana-checker --save-dev

To use Banana checker as part of your test run, refer to the banana-checker program from the scripts.test property in your package.json file.

{
	"scripts": {
		"test": "banana-checker i18n/"
	}
}

To set custom options, pass parameters as --key=value pairs. For example:

npx banana-checker --requireKeyPrefix="x-" i18n/

• For boolean options, use the valus 0, 1, true, or false.
• Quotes are allowed, but not required.
• For options that allow multiple values, separate values by comma. Like --key=one,two.

Options

For edge cases, you can set some path options:

sourceFile

Type: string Default value: "en.json"

The JSON file providing the primary messages.

documentationFile

Type: string Default value: "qqq.json"

The JSON file providing the documentation messages.

requireMetadata

Type: boolean Default value: true

Whether to fail if message files don't have a @metadata meta-data key.

requireCompleteMessageDocumentation

Type: boolean Default value: true

Whether to fail if any message is in the primary file but not documented.

disallowEmptyDocumentation

Type: boolean Default value: true

Whether to fail if any message is in the primary file but documented as a blank string.

requireLowerCase

Type: boolean or "initial" Default value: true

Whether to fail if any message key is not lower case. If set to "initial", fail only if the first character is not lower case.

requireKeyPrefix

Type: string or string[] Default value: []

Whether to fail if any message key is not prefixed by the given prefix, or if multiple, one of the given prefixes.

disallowUnusedDocumentation

Type: boolean Default value: true

Whether to fail if any documented message isn't in the primary file.

disallowBlankTranslations

Type: boolean Default value: true

Whether to fail if any message is translated as a blank string.

disallowDuplicateTranslations

Type: boolean Default value: false

Whether to fail if any message is translated as identical to the original string.

disallowUnusedTranslations

Type: boolean Default value: false

Whether to fail if any translated message isn't in the primary file.

requireCompletelyUsedParameters

Type: boolean Default value: false

Whether to fail if any translated message fails to use a parameter used in the primary message.

requireCompleteTranslationLanguages

Type: string[] Default value: [] Example value: [ 'fr', 'es' ]

Languages on which to fail if any message in the primary file is missing.

requireCompleteTranslationMessages

Type: string[] Default value: [] Example value: [ 'first-message-key', 'third-message-key' ]

Messages on which to fail if missing in any provided language.

ignoreMissingBlankTranslations

Type: boolean Default value: true

Whether to ignore missing translations whose original string is blank.

allowLeadingWhitespace

Type: boolean Default value: true

Whether to ignore leading whitespace in original or translated messages.

allowTrailingWhitespace

Type: boolean Default value: false

Whether to ignore trailing whitespace in original or translated messages.