webpack-static-i18n-plugin

A webpack plugin implementing node-static-i18n for generating internationalized HTML files.

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 webpack output.path. Because the plugin prefixes the file paths with the locale code path/to/file.html would become en/path/to/file.html, it/path/to/file.html etc. However, if the hosting environment expects the files to be in path/to folder this is not okay. In that case setting outputPrefix to path/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 if outputDefault 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 set suppressRaw: 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/