Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript. Learn more »


1.0.1 • Public • Published

gulp-browser-i18n-localize NPM version Build status

A gulp plugin that hardcodes localized messages into files that utilize browser internationalization APIs (browser.i18n.* / chrome.i18n.*).


This gulp plugin was originally written to help convert browser web extensions into legacy userscripts. Proper web extensions support translations, which is easy enough to do with the browser APIs, but those APIs are not available to userscripts. Using this plugin, a web extension with translations can be built into a userscript (or a series of userscripts, for all supported locales) where the API functionality is replaced with the hard-coded translations for each locale.


First, install gulp-browser-i18n-localize as a development dependency:

npm install --save-dev gulp-browser-i18n-localize

Then, add it to your gulpfile.js:

Basic Configuration

var localize = require('gulp-browser-i18n-localize');
gulp.task('templates', function(){



Type: string

Default: _locales

Description: Specifies the path to the root directory for the locales (this path should end in _locales), since that is the convention specified for Web Extensions (see Providing localized strings in _locales on MDN).


Type: array

Default: []

Description: Specifies the locales to use. When empty, all available locales (from the _locales directory) are used.


Type: string

Default: $filename.$locale.$ext

Description: Specifies the naming schema used for the localized files in the stream/buffer. The default schema inserts the locale name used just before the extension (i.e. myfile.en-US.js). To disable renaming, set schema to false. Note that you should NOT disable renaming if you are using multiple locales, as you will not be able to write out all of the files at the end of your task (since they will all have the same name).

NOTE: Empty files are not renamed in the stream/buffer.

Placeholder Description Example Value
$filename This is the original file name, minus path and extension myfile
$locale This is the locale used during processing en-US
$ext This is the original file's extension (minus leading period) js

You could use /$locale/$filename.$ext to place all translated files into sub-directories corresponding to their locale.


Type: string

Default: ltr

Description: Specifies the BIDI direction string to be inserted wherever BIDI methods/messages are used.


Type: RegExp

Default: /__MSG_([\S]+)__/gi

Description: Specifies the regular expression used to find __MSG_ + messageName + __ strings. This regular expression should include one capture group that will contain the actual message name.


Type: RegExp

Default: /(?:browser|chrome)\.i18n\.([a-zA-Z]+)\(([^\)]+)?\)/gi

Description: Specifies the regular expression used to find browser.i18n.* and chrome.i18n.* methods. This regular expression should include two capture groups: one for the method name, and one for the (optional) arguments supplied to the method.


npm i gulp-browser-i18n-localize

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability