i18n-lint
v1.1.0
Published
Lint HTML and template source files for hardcoded (untranslated) strings
Downloads
17,770
Maintainers
Readme
i18n-lint
Detect possible instances of untranslated strings being used in HTML and HTML-derived template languages
i18n-lint
is a tool for detecting hardcoded (untranslated) strings in HTML and template source files. It can be used a CLI utility, or as library.
i18n-lint
detects instances where a HTML element's text node or certain attributes look like a hardcoded string.
See https://jwarby.github.io/i18n-lint/ for the full documentation and demos.
Getting started
Installing
Install using npm:
$ npm install -g jwarby/i18n-lint
Installing globally will give you access to the i18n-lint
binary from anywhere.
Documentation
See https://jwarby.github.io/i18n-lint/ for the full documentation.
CLI
The CLI program is called i18n-lint
, and will be available once i18n-lint
has been installed globally.
Usage:
$ i18n-lint [OPTIONS] <file ...>
Program help and information
- Run
i18n-lint --help
ori18n-lint -h
to display help output and then exit - Run
i18n-lint --version
ori18n-lint -V
to display version and then exit - Run
man i18n-lint
on systems which supportman
to view the Linux manual page
Linting files
To lint a file, call i18n-lint <file>
:
$ i18n-lint some_file.html
You can use a glob pattern too:
$ i18n-lint app/views/**/*.html
Options
-h, --help
Display help and then exit
-V, --version
Display version information and then exit
-t, --template-delimiters <delimiters>
Set the template delimiters which the source files use. The value should be the start and
end delimiters, separated by a comma. For example, if running
i18n-lint
against template files which use a Mustache-like syntax, use the following:
$ i18n-lint -t "{{,}}" views/**/*.hbs
Similarly, but for EJS-syntax:
$ i18n-lint -t "<%,%>" views/**/*.ejs
-a, --attributes <attributes>
default: alt,placeholder,title
A comma-separated list of which HTML attributes should be checked.
-i, --ignore-tags <tags>
default: style,script
A comma-separated list of HTML tags to ignore when searching for hardcoded strings.
-r, --reporter <reporter>
default: default
The reporter to use when outputting information. The reporters follow the same structure as
JSHint reporters, and the i18n-lint
library reports error in the same manner as JSHint - this
means you can use any existing JSHint reporters as reporters for i18n-lint
!
There are 3 built-in reporters that get shipped with i18n-lint
: default
, unix
and json
.
To write your own reporters, look to lib/reporters/*.js
as a starting point.
--exclude <patterns>
A comma-separated list of file patterns to exclude, such as 'docs/,ignored.html'
.
--color/--no-color
Maintain/turn off colored output. For more info, see https://www.npmjs.com/package/chalk#chalk-supportscolor.
Exit Status
0
: if everything went OK, and no hardcoded strings were found1
: if hardcoded strings were found64
: command-line usage error, e.g. no input files provided ([EX_USAGE]
)66
: cannot open input, e.g. input files I/O error, specified reporter file does not exist ([EX_NOINPUT]
)70
: internal software error ([EX_SOFTWARE]
)
Colored Output
To maintain colored output, run i18n-lint
with the --color
flag:
$ i18n-lint --color **/*.html | less -R
Library
To use i18n-lint
as a library, install it locally and require
it in your projects:
$ npm install --save-dev i18n-lint
var I18nLint = require('i18n-lint');
var errors = I18nLint('some_file.ejs', {
templateDelimiters: [['<%','%>']],
attributes: ['title', 'alt', 'data-custom-attr']
});
Note: prior to v1.1.0, only a single set of template delimiters could be passed. However, the legacy single-depth API is still supported, ie:
templateDelimiters: ['<%', '%>']
will still work (but is not recommended).
If you want to scan a string instead of reading in a file, you can use the scan
function:
var I18nLint = require('i18n-lint');
var context = '<h1>Some hardcoded string</h1>\n<br>\n<p>\ncontent not translated</p>';
var options = {
// ...snip...
};
var errors = I18nLint.scan(context, options);
The scan function can also accept a fileName
parameter:
var I18nLint = require('i18n-lint');
var stdin = '';
// Read stdin stream
// ...snip...
// Once stdin has finished...
var errors = I18nLint(context, options, 'stdin');
This allows more meaningful output when the reporters print a filename.
Options
Options are passed as an object, as the second parameter to i18n-lint
.
templateDelimiters
type: Array
, default: []
Specify the start and end template delimiters which the source files use. We can specify multiple delimiters if needed. For example, when linting EJS files:
I18nLint('file.ejs', {
templateDelimiters: [['<%', '%>']]
});
attributes
type: Array
, default: ['alt', 'placeholder', 'title']
Specify which HTML attributes to check when searching for hardcoded strings.
ignoreTags
type: Array
, default: ['style', 'script', 'pre', 'code']
An array of tags which should be ignored when searching for hardcoded strings.
Using Reporters
When using i18n-lint
as a library, you can still use the reporters:
console.log(I18nLint.reporters);
// {
// default: [Function]
// }
var reporter = I18nLint.reporters.default;
var errors = I18nLint('file.html', {});
reporter(errors);
There are currently 3 built-in reporters: default
, unix
and json
.
To use other reporters, simply require them:
var I18nLint = require('i18n-lint');
var reporter = require('i18n-lint-awesome-reporter');
reporter(I18nLint('file.html', {}));
Error Format
{
file: '', // string, file which contains the errors,
error: {
id: String, // usually '(error)'
code: String, // warning code (see Warning Numbers)
reason: String, // message describing the error
evidence: RegExp, // with the offending text in match groups
line: Number, // line number of the error
character: Number, // column where evidence begins
scope: String // where the error was found
}
}
Grunt
There is a grunt task which wraps i18n-lint
's functionality, which
can be found at https://github.com/jwarby/grunt-i18n-lint.
Warning Numbers
W001
: hardcoded text node foundW002
: hardcoded attribute value found
Contributing
See CONTRIBUTING.md.
Running Tests
npm test
- lints JS files in
bin/
,lib/
andtest/
- runs
mocha
test suite
- lints JS files in
Generate Code Coverage Report
npm run-script coverage
- coverage is output to a
./coverage
directory
- coverage is output to a
Release History
i18n-lint
follows SemVer rules for version numbers.
v1.1.0
23rd Aug 2020
- Support for more than one set of template delimiters add - thanks @alexmorvan
v1.0.0
18th Sep 2019
First published release.
License
Copyright (c) 2015 James Warwood. Licensed under the MIT license.
Authors
See AUTHORS.txt.
Acknowledgements
- CLI app scaffolding from https://github.com/Hypercubed/generator-commander