webpack-static-i18n-plugin
v1.0.1
Published
A webpack plugin implementing node-static-i18n for generating internationalized HTML files.
Downloads
31
Readme
webpack-static-i18n-plugin
A webpack plugin implementing node-static-i18n for generating internationalized HTML files.
Based on webpack-static-i18n-html.
Introduction
The node-static-i18n utility provides convenient way to quickly generate different language versions of static assets. While there is a Grunt plugin and a gulp plugin available, the existing integration with webpack may fall short in certain situations.
webpack-static-i18n-html vs. webpack-static-i18n-plugin
webpack-static-i18n-html
The original plugin this one based on does not use the standard webpack asset processing and loaders. Instead, it executes an independent job using node-static-i18n
at the compile
hook. It may be adequate in certain situations, where someone only needs a quick way to attach a node-static-i18n
step to their webpack workflow, but it is important to note, that the process executed is not related to the files being processed by webpack. It is an independent node-static-i18n
job, which based on the options may actually translate files into the output folder, but is unable to cooperate with other plugins for managing those files. This becomes apparent as soon as someone tries to use it together with Clean plugin for webpack; since the assets generated by the node-static-i18n
job are not registered with webpack as output assets, the Clean plugin deletes them every time after they are created effectively rendering the translations impossible.
webpack-static-i18n-plugin
This plugin instead uses the webpack assets model to create translations, therefore those assets can be properly manipulated by other plugins resulting in greater compatibility.
Note however that since this plugin works with the assets processed by webpack, the node-static-i18n
translations will not run against your filesystem, but the files in the memory being processed by webpack. This means some of the configuration parameters (like exclude
, baseDir
and outputDir
) are ignored, since the directories and files are always defined by your webpack configuration and loader plugins.
Installation
Install using npm, e.g.:
npm install --save-dev webpack-static-i18n-plugin
Usage
Loading files
Since this plugin relies on webpack to load the assets to be translated, the key to usage is to load all HTML (or other translatable) files as assets.
This can be done easily by the HTML Webpack Plugin, which may be already used in many projects as the solution to include the script and style entry points to the html files. HTML Webpack Plugin may only load one HTML file, but you can always add more instances to the plugins
array to handle multiple files.
For other file types you may need other plugins to load them, but it is always specific to the exact file type and your use-case. Just keep in mind, once the files are loaded by webpack, the translations can be applied to them.
Translating files
The plugin accepts almost all the same options as node-static-i18n. Some parameters however don't work, because now webpack is handling the loading and the emitting of the files, so for example exclude
, baseDir
and outputDir
are ignored. Options controlling the way of the translation are expected to work the same way. The files
option is expected to work, however the implementation is not the same. It uses minimatch to process a glob like pattern and should behave the same, but small differences could appear. Please report any unexpected behaviour as issue!
On top of the node-static-i18n options the plugin provides few more settings:
outputPrefix
(string, default:''
): May be useful when the html files are not on the same level as the webpackoutput.path
. Because the plugin prefixes the file paths with the locale codepath/to/file.html
would becomeen/path/to/file.html
,it/path/to/file.html
etc. However, if the hosting environment expects the files to be inpath/to
folder this is not okay. In that case settingoutputPrefix
topath/to/
will adjust the output files to be:path/to/en/file.html
,path/to/it/file.html
etc.suppressRaw
(bool, default:false
): If set to true, the raw, untranslated files are not written into the output folder. This has no effect ifoutputDefault
is left on default, because in that case the default locale version will replace the untranslated files anyway. But if for example all language variants are written to a locale prefixed folder (i.e.outputDefault: '__lng__/__file__'
), it is recommended to setsuppressRaw: true
to avoid the untranslated files in the output folder.
Sample webpack.config.js
:
import path from 'path';
import WebpackStaticI18NPlugin from 'webpack-static-i18n-plugin';
import HtmlWebpackPlugin from 'html-webpack-plugin';
module.exports = {
entry : 'index.js',
output : {
path : __dirname + '/dist',
filename: 'bundle.js'
},
plugins: [
new HtmlWebpackPlugin({
filename: 'index.html',
template: path.resolve(__dirname, 'index.html'),
}),
new HtmlWebpackPlugin({
filename: 'another-page.html',
template: path.resolve(__dirname, 'another-page.html'),
}),
new StaticI18nHtmlPlugin({
locale : 'en', // The default locale
locales: ['en', 'de'],
outputDefault: '__lng__/__file__', // default: '__file__'
outputOther : '__lng__/__file__', // default: '__lng__/__file__'
localesPath : path.join(__dirname, 'locales/'),
files : '*.html',
})
]
}
Advanced usage
Loading all HTML files automatically
If you have a lot of HTML files adding them manually as HtmlWebpackPlugin
instances into webpack.config.js
can be tedious. A nice solution is available in Static Site Boilerplate (MIT license). Based on their code one could write something like this:
const generateHTMLPlugins = () => glob
.sync(path.join(__dirname, '/**/*.html'))
.map((filepath) => {
return new HtmlWebpackPlugin({
filename: path.relative(__dirname, filepath),
template: filepath,
});
}
);
module.exports = {
//...
plugins: [
...generateHTMLPlugins(),
new StaticI18nHtmlPlugin({ /* ... */ })
]
}
Issues
There are no known issues yet, but feel free to report any problems or suggestions here: https://github.com/BenceSzalai/webpack-static-i18n-plugin/issues
Bence Szalai - https://sbnc.eu/