grunt-banana-checker
v0.13.0
Published
Checker for the 'Banana' JSON-file format for interface messages, as used by MediaWiki and jQuery.i18n.
Downloads
21,233
Readme
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:
Ensure your project has a Gruntfile.js file (example file). Then, in Gruntfile.js, add the line:
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:
You can also configure multiple directories, like so:
You can also use globbing patterns and/or arrays of directories, like so:
For a full list of supported ways of defining the target directory of a Grunt plugin, see Configuring tasks on gruntjs.com.
See the Options sections for create a config file.
Config can also be set in Grunt by defining your target directory as an object instead of a string, with src
and options
properties, like so:
For all available options, see the Options section.
Command-line
The Banana checker also offers a command-line interface.
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.
Options can be set in the config file, or overridden as --key=value
pairs. For example:
- For boolean options, use the valus
0
,1
,true
, orfalse
. - Quotes are allowed, but not required.
- For options that allow multiple values, separate values by comma. Like
--key=one,two
.
Options
Create a .bananaconfig.[json|js]
file (or bananaconfig.[json|js]
):
Available options are:
autofix
Type: boolean
Default value: false
If enabled, try to automatically fix issues in en/qqq.json detected by some checks.
Note that autofixing will not affect the check result - the checker will fail even if all errors were automatically fixed.
autofixTranslated
Type: boolean
Default value: false
Same as autofix
but for translated messages.
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.
Rules
Rule options can be set to "off"
, "warn"
or "error"
. When additional options are available an array
tuple should be created, e.g. [ "error", { "initial: true } ]
.
requireMetadata
Default value: "error"
Whether to fail if message files don't have a @metadata
meta-data key.
requireCompleteMessageDocumentation
Default value: "error"
Additional option: skip
(type string[]
) Keys to skip
Whether to fail if any message is in the primary file but not documented.
disallowEmptyDocumentation
Default value: "error"
Whether to fail if any message is in the primary file but documented as a blank string.
requireLowerCase
Default value: "error"
Additional option: initial
(type boolean
, default false
)
Whether to fail if any message key is not lower case. If the "initial"
option is set,
fail only if the first character is not lower case.
requireKeyPrefix
Default value: "off"
Additional option: prefix
(type string
or string[]
)
Whether to fail if any message key is not prefixed by the given prefix, or if multiple, one of the given prefixes.
disallowUnusedDocumentation
Default value: "error"
Whether to fail if any documented message isn't in the primary file.
disallowBlankTranslations
Default value: "warn"
Whether to warn if any message is translated as a blank string.
disallowDuplicateTranslations
Default value: "off"
Whether to fail if any message is translated as identical to the original string.
disallowUnusedTranslations
Default value: "off"
Whether to fail if any translated message isn't in the primary file.
requireCompletelyUsedParameters
Default value: "off"
Whether to fail if any translated message fails to use a parameter used in the primary message.
requireCompleteTranslationLanguages
Default value: "off"
Additional option: langs
(type string[]
) Languages required
Additional option: ignoreMissing
(type boolean
, default true
) Ignore missing translations whose original string is blank
Example value: [ "error", { "langs": [ "fr", "es" ], "ignoreMissing": false } ]
Languages on which to fail if any message in the primary file is missing.
requireCompleteTranslationMessages
Default value: "off"
Additional option: keys
(type string[]
) Message keys to require
Example value: [ "error", { "keys": [ "first-message-key", "second-message-key" ] } ]
Messages on which to fail if missing in any provided language.
disallowLeadingWhitespace
Default value: "off"
Whether to ignore leading whitespace in original messages.
disallowLeadingWhitespaceTranslated
Default value: "off"
Whether to ignore leading whitespace in translated messages.
disallowTrailingWhitespace
Default value: "error"
Whether to ignore trailing whitespace in original messages.
allowTrailingWhitespaceTranslated
Default value: "warn"
Whether to ignore trailing whitespace in original messages.