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 documentated.
- 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 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 configuation 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 prefices.
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: true
Whether to ignore trailing whitespace in original or translated messages.