i18next-scanner
Advanced tools
Scan your code, extract translation keys/values, and merge them into i18n resource files.
Scan your code, extract translation keys/values, and merge them into i18n resource files.
Turns your code
i18n._('Loading...');
i18n._('Backslashes in single quote: \' \\ \'');
i18n._('This is \
a multiline \
string');
i18n.t('car', { context: 'blue', count: 1 }); // output: 'One blue car'
i18n.t('car', { context: 'blue', count: 2 }); // output: '2 blue cars'
<Trans i18nKey="some.key">Default text</Trans>
into resource files
{
"Loading...": "Wird geladen...", // uses existing translation
"Backslashes in single quote: ' \\ '": "__NOT_TRANSLATED__", // returns a custom string
"This is a multiline string": "this is a multiline string", // returns the key as the default value
"car": "car",
"car_blue": "One blue car",
"car_blue_plural": "{{count}} blue cars",
"some": {
"key": "Default text"
}
}
There is a major breaking change since v1.0, and the API interface and options are not compatible with v0.x.
Checkout Migration Guide while upgrading from earlier versions.
npm install --save-dev i18next-scanner
or
npm install -g i18next-scanner
$ i18next-scanner
Usage: i18next-scanner [options] <file ...>
Options:
-V, --version output the version number
--config <config> Path to the config file (default: i18next-scanner.config.js)
--output <path> Path to the output directory (default: .)
-h, --help output usage information
Examples:
$ i18next-scanner --config i18next-scanner.config.js --output /path/to/output 'src/**/*.{js,jsx}'
$ i18next-scanner --config i18next-scanner.config.js 'src/**/*.{js,jsx}'
$ i18next-scanner '/path/to/src/app.js' '/path/to/assets/index.html'
Globbing patterns are supported for specifying file paths:
* matches any number of characters, but not /? matches a single character, but not /** matches any number of characters, including /, as long as it's the only thing in a path part{} allows for a comma-separated list of "or" expressions! at the beginning of a pattern will negate the matchvar fs = require('fs');
var chalk = require('chalk');
module.exports = {
options: {
debug: true,
func: {
list: ['i18next.t', 'i18n.t']
},
lngs: ['en','de'],
ns: [
'locale',
'resource'
],
defaultNs: 'resource',
defaultValue: '__STRING_NOT_TRANSLATED__',
resource: {
loadPath: 'i18n/{{lng}}/{{ns}}.json',
savePath: 'i18n/{{lng}}/{{ns}}.json'
},
nsSeparator: false, // namespace separator
keySeparator: false, // key separator
interpolation: {
prefix: '{{',
suffix: '}}'
}
},
transform: function customTransform(file, enc, done) {
"use strict";
const parser = this.parser;
const content = fs.readFileSync(file.path, enc);
let count = 0;
parser.parseFuncFromString(content, { list: ['i18next._', 'i18next.__'] }, (key, options) => {
parser.set(key, Object.assign({}, options, {
nsSeparator: false,
keySeparator: false
}));
++count;
});
if (count > 0) {
console.log(`i18next-scanner: count=${chalk.cyan(count)}, file=${chalk.yellow(JSON.stringify(file.relative))}`);
}
done();
}
};
const fs = require('fs');
const Parser = require('i18next-scanner').Parser;
const customHandler = function(key) {
parser.set(key, '__TRANSLATION__');
};
const parser = new Parser();
const content = '';
// Parse Translation Function
// i18next.t('key');
content = fs.readFileSync('/path/to/app.js', 'utf-8');
parser
.parseFuncFromString(content, customHandler) // pass a custom handler
.parseFuncFromString(content, { list: ['i18next.t']}) // override `func.list`
.parseFuncFromString(content, { list: ['i18next.t']}, customHandler)
.parseFuncFromString(content); // use default options and handler
// Parse Trans component
content = fs.readFileSync('/path/to/app.jsx', 'utf-8');
parser
.parseFuncFromString(content, customHandler) // pass a custom handler
.parseFuncFromString(content); // use default options and handler
// Parse HTML Attribute
// <div data-i18n="key"></div>
content = fs.readFileSync('/path/to/index.html', 'utf-8');
parser
.parseAttrFromString(content, customHandler) // pass a custom handler
.parseAttrFromString(content, { list: ['data-i18n'] }) // override `attr.list`
.parseAttrFromString(content, { list: ['data-i18n'] }, customHandler)
.parseAttrFromString(content); // using default options and handler
console.log(parser.get());
console.log(parser.get({ sort: true }));
console.log(parser.get('translation:key', { lng: 'en'}));
The main entry function of i18next-scanner is a transform stream. You can use vinyl-fs to create a readable stream, pipe the stream through i18next-scanner to transform your code into an i18n resource object, and write to a destination folder.
Here is a simple example showing how that works:
const scanner = require('i18next-scanner');
const vfs = require('vinyl-fs');
const sort = require('gulp-sort');
const options = {
// See options at https://github.com/i18next/i18next-scanner#options
};
vfs.src(['/path/to/src'])
.pipe(sort()) // Sort files in stream by path
.pipe(scanner(options))
.pipe(vfs.dest('/path/to/dest'));
Alternatively, you can get a transform stream by calling createStream() as show below:
vfs.src(['/path/to/src'])
.pipe(sort()) // Sort files in stream by path
.pipe(scanner.createStream(options))
.pipe(vfs.dest('/path/to/dest'));
Now you are ready to set up a minimal configuration, and get started with Gulp. For example:
const gulp = require('gulp');
const sort = require('gulp-sort');
const scanner = require('i18next-scanner');
gulp.task('i18next', function() {
return gulp.src(['src/**/*.{js,html}'])
.pipe(sort()) // Sort files in stream by path
.pipe(scanner({
lngs: ['en', 'de'], // supported languages
resource: {
// the source path is relative to current working directory
loadPath: 'assets/i18n/{{lng}}/{{ns}}.json',
// the destination path is relative to your `gulp.dest()` path
savePath: 'i18n/{{lng}}/{{ns}}.json'
}
}))
.pipe(gulp.dest('assets'));
});
Once you've finished the installation, add this line to your project's Gruntfile:
grunt.loadNpmTasks('i18next-scanner');
In your project's Gruntfile, add a section named i18next to the data object passed into grunt.initConfig(), like so:
grunt.initConfig({
i18next: {
dev: {
src: 'src/**/*.{js,html}',
dest: 'assets',
options: {
lngs: ['en', 'de'],
resource: {
loadPath: 'assets/i18n/{{lng}}/{{ns}}.json',
savePath: 'i18n/{{lng}}/{{ns}}.json'
}
}
}
}
});
There are two ways to use i18next-scanner:
const Parser = require('i18next-scanner').Parser;
const parser = new Parser(options);
const code = "i18next.t('key'); ...";
parser.parseFuncFromString(code);
const jsx = '<Trans i18nKey="some.key">Default text</Trans>';
parser.parseTransFromString(jsx);
const html = '<div data-i18n="key"></div>';
parser.parseAttrFromString(html);
parser.get();
Parse translation key from JS function
parser.parseFuncFromString(content)
parser.parseFuncFromString(content, { list: ['_t'] });
parser.parseFuncFromString(content, function(key, options) {
options.defaultValue = key; // use key as the value
parser.set(key, options);
});
parser.parseFuncFromString(content, { list: ['_t'] }, function(key, options) {
parser.set(key, options); // use defaultValue
});
Parse translation key from the Trans component
parser.parseTransFromString(content);
parser.parseTransFromString(content, function(key, options) {
options.defaultValue = key; // use key as the value
parser.set(key, options);
});
Parse translation key from HTML attribute
parser.parseAttrFromString(content)
parser.parseAttrFromString(content, { list: ['data-i18n'] });
parser.parseAttrFromString(content, function(key) {
var defaultValue = key; // use key as the value
parser.set(key, defaultValue);
});
parser.parseAttrFromString(content, { list: ['data-i18n'] }, function(key) {
parser.set(key); // use defaultValue
});
Get the value of a translation key or the whole i18n resource store
// Returns the whole i18n resource store
parser.get();
// Returns the resource store with the top-level keys sorted by alphabetical order
parser.get({ sort: true });
// Returns a value in fallback language (@see options.fallbackLng) with namespace and key
parser.get('ns:key');
// Returns a value with namespace, key, and lng
parser.get('ns:key', { lng: 'en' });
Set a translation key with an optional defaultValue to i18n resource store
// Set a translation key
parser.set(key);
// Set a translation key with default value
parser.set(key, defaultValue);
// Set a translation key with default value using options
parser.set(key, {
defaultValue: defaultValue
});
var scanner = require('i18next-scanner');
scanner.createStream(options, customTransform /* optional */, customFlush /* optional */);
The optional customTransform function is provided as the 2nd argument for the transform stream API. It must have the following signature: function (file, encoding, done) {}. A minimal implementation should call the done() function to indicate that the transformation is done, even if that transformation means discarding the file.
For example:
var scanner = require('i18next-scanner');
var vfs = require('vinyl-fs');
var customTransform = function _transform(file, enc, done) {
var parser = this.parser;
var content = fs.readFileSync(file.path, enc);
// add your code
done();
};
vfs.src(['/path/to/src'])
.pipe(scanner(options, customTransform))
.pipe(vfs.dest('path/to/dest'));
To parse a translation key, call parser.set(key, defaultValue) to assign the key with an optional defaultValue.
For example:
var customTransform = function _transform(file, enc, done) {
var parser = this.parser;
var content = fs.readFileSync(file.path, enc);
parser.parseFuncFromString(content, { list: ['i18n.t'] }, function(key) {
var defaultValue = '__L10N__';
parser.set(key, defaultValue);
});
done();
};
Alternatively, you may call parser.set(defaultKey, value) to assign the value with a default key. The defaultKey should be unique string and can never be null, undefined, or empty.
For example:
var hash = require('sha1');
var customTransform = function _transform(file, enc, done) {
var parser = this.parser;
var content = fs.readFileSync(file.path, enc);
parser.parseFuncFromString(content, { list: ['i18n._'] }, function(key) {
var value = key;
var defaultKey = hash(value);
parser.set(defaultKey, value);
});
done();
};
The optional customFlush function is provided as the last argument for the transform stream API, it is called just prior to the stream ending. You can implement your customFlush function to override the default flush function. When everything's done, call the done() function to indicate the stream is finished.
For example:
var scanner = require('i18next-scanner');
var vfs = require('vinyl-fs');
var customFlush = function _flush(done) {
var parser = this.parser;
var resStore = parser.getResourceStore();
// loop over the resStore
Object.keys(resStore).forEach(function(lng) {
var namespaces = resStore[lng];
Object.keys(namespaces).forEach(function(ns) {
var obj = namespaces[ns];
// add your code
});
});
done();
};
vfs.src(['/path/to/src'])
.pipe(scanner(options, customTransform, customFlush))
.pipe(vfs.dest('/path/to/dest'));
Below are the configuration options with their default values:
{
debug: false,
removeUnusedKeys: false,
sort: false,
attr: {
list: ['data-i18n'],
extensions: ['.html', '.htm']
},
func: {
list: ['i18next.t', 'i18n.t'],
extensions: ['.js', '.jsx']
},
lngs: ['en'],
ns: ['translation'],
defaultNs: 'translation',
defaultValue: '',
resource: {
loadPath: 'i18n/{{lng}}/{{ns}}.json',
savePath: 'i18n/{{lng}}/{{ns}}.json',
},
nsSeparator: ':',
keySeparator: '.',
pluralSeparator: '_',
contextSeparator: '_',
interpolation: {
pefix: '{{',
suffix: '}}'
}
}
Type: Boolean Default: false
Set to true to trun on debug output.
Type: Boolean Default: false
Set to true to remove unused translation keys from i18n resource files.
Type: Boolean Default: false
Set to true if you want to sort translation keys in ascending order.
Type: Object or false
If an Object is supplied, you can either specify a list of attributes and extensions, or override the default.
{ // Default
attr: {
list: ['data-i18n'],
extensions: ['.html', '.htm']
}
}
You can set attr to false to disable parsing attribute as below:
{
attr: false
}
Type: Object or false
If an Object is supplied, you can either specify a list of translation functions and extensions, or override the default.
{ // Default
func: {
list: ['i18next.t', 'i18n.t'],
extensions: ['.js', '.jsx']
}
}
You can set func to false to disable parsing translation function as below:
{
func: false
}
Type: Array Default: ['en']
An array of supported languages.
Type: String or Array Default: ['translation']
A namespace string or an array of namespaces.
Type: String Default: 'translation'
The default namespace used if not passed to translation function.
Type: String or Function Default: ''
The default value used if not passed to parser.set.
Provides the default value with a string:
{
defaultValue: '__NOT_TRANSLATED__'
}
Provides the default value as a callback function:
{
// @param {string} lng The language currently used.
// @param {string} ns The namespace currently used.
// @param {string} key The translation key.
// @return {string} Returns a default value for the translation key.
defaultValue: function(lng, ns, key) {
if (lng === 'en') {
// Return key as the default value for English language
return key;
}
// Return the string '__NOT_TRANSLATED__' for other languages
return '__NOT_TRANSLATED__';
}
}
Type: Object
Resource options:
{ // Default
resource: {
// path where resources get loaded from
loadPath: 'i18n/{{lng}}/{{ns}}.json',
// path to store resources
savePath: 'i18n/{{lng}}/{{ns}}.json',
// jsonIndent to use when storing json files
jsonIndent: 2
}
}
Type: String or false Default: '.'
Key separator used in translation keys.
Set to false to disable key separator if you prefer having keys as the fallback for translation (e.g. gettext). This feature is supported by i18next@2.1.0. Also see Key based fallback at http://i18next.com/translate/keyBasedFallback.
Type: String or false Default: ':'
Namespace separator used in translation keys.
Set to false to disable namespace separator if you prefer having keys as the fallback for translation (e.g. gettext). This feature is supported by i18next@2.1.0. Also see Key based fallback at http://i18next.com/translate/keyBasedFallback.
Type: Boolean or Function Default: true
Whether to add context form key.
context: function(lng, ns, key, options) {
return true;
}
Type: Boolean Default: true
Whether to add a fallback key as well as the context form key.
Type: String Default: '_'
The character to split context from key.
Type: Boolean or Function Default: true
Whether to add plural form key.
plural: function(lng, ns, key, options) {
return true;
}
Type: Boolean Default: true
Whether to add a fallback key as well as the plural form key.
Type: String Default: '_'
The character to split plural from key.
Type: Object
interpolation options
{ // Default
interpolation: {
// The prefix for variables
prefix: '{{',
// The suffix for variables
suffix: '}}'
}
}
Checkout Integration Guide to learn how to integrate with React, Gettext Style I18n, and Handlebars.
MIT
FAQs
Scan your code, extract translation keys/values, and merge them into i18n resource files.
The npm package i18next-scanner receives a total of 98,336 weekly downloads. As such, i18next-scanner popularity was classified as popular.
We found that i18next-scanner demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.