i18n-lint

1.1.0 verified Fri May 01 auth: no javascript

i18n-lint (v1.1.0) is a CLI and library tool for detecting hardcoded (untranslated) strings in HTML and template source files. It checks text nodes and attributes (default: alt, placeholder, title) against a list of built-in internationalization functions like `gettext()` and `i18n()`. Supports custom template delimiters (e.g., {{ }}, <%%>) for Mustache/Handlebars/EJS. Compiled with JSHint-compatible reporters and built-in default/unix/json output. Designed for Node.js >=0.8.0, with global install providing the `i18n-lint` binary. Key differentiator: it integrates linting into existing build pipelines via CLI or Node API, unlike gettext extraction tools.

Common errors

error Error: Cannot find module 'i18n-lint' ↓

cause Package not installed or installed globally but not in node_modules.

fix

Run npm install i18n-lint or npm install -g i18n-lint.

error TypeError: i18nLint is not a function ↓

cause Incorrect import (e.g., default import used on CJS build).

fix

Use import i18nLint from 'i18n-lint' if using ESM; otherwise if CJS, use const i18nLint = require('i18n-lint').default.

error Error: Repoter "custom.js" not found ↓

cause Path to custom reporter file is incorrect or file doesn't exist.

fix

Use absolute path or ensure file is relative to current working directory. E.g., --reporter /path/to/reporter.js.

error SyntaxError: Unexpected token ILLEGAL (in template parsing) ↓

cause Template delimiters not matching actual template syntax.

fix

Specify correct delimiters with -t option, e.g., -t "{{,}}" for Handlebars, -t "<%,%>" for EJS.

Warnings

gotcha Template delimiters option must be a comma-separated string or array, but if passed incorrectly may cause no errors to be reported. ↓

fix Use -t "{{,}}" for CLI or templateDelimiters: ['{{', '}}'] for API.

gotcha Default attributes checked are alt, placeholder, title; other attributes like data-* or aria-* are ignored unless specified via -a or attributes option. ↓

fix Use --attributes "aria-label,custom-attr" to include more.

gotcha The tool may report false positives for strings that are actually used as keys in a translation function but not recognized due to missing function patterns. ↓

fix Configure custom translation function names via options or .i18n-lintrc config file.

gotcha Exit code 1 indicates hardcoded strings found; exit code 0 means clean. Exit code 64 for usage errors. ↓

fix Use --help for usage. Ensure input files exist.

deprecated Options via .i18n-lintrc (YAML) are supported but undocumented; may change. ↓

fix Consider using programmatic API or CLI flags instead.

breaking Version 1.0.0 dropped support for Node <0.8.0 and changed default reporters. ↓

fix Update to latest version (1.1.0). If using custom reporter, ensure compatibility.

Install

npm install i18n-lint

yarn add i18n-lint

pnpm add i18n-lint

Imports

i18n-lint

wrong

const i18nLint = require('i18n-lint');

correct

import i18nLint from 'i18n-lint';
const results = i18nLint('file.html');

Package uses ESM exports. CJS require() may not work due to module format.

cli

wrong

const run = require('i18n-lint/cli').run;

correct

import { run } from 'i18n-lint/cli.js';
run(['file.html']);

CLI entry point exposed for programmatic use; ensure correct path.

Linter

wrong

const Linter = require('i18n-lint').Linter;

correct

import { Linter } from 'i18n-lint';
const linter = new Linter({ templateDelimiters: ['{{', '}}'] });

Linter class available from main export. Requires options object.

Quickstart

Basic usage: lint an HTML string for hardcoded text, logging results.

import i18nLint from 'i18n-lint';
// Lint a string with default options
const results = i18nLint('<p>Hello, world!</p>');
console.log(results);
// Output: Array of error objects like { line: 1, col: 3, message: 'Possible untranslated string...' }