Internationalization Plugin for Webpack
- Webpack configuration
- Building libraries
- Plugin configuration
- Loader configuration
Webpack plugin with loader for build locales according to component approach
This is webpack plugin designed to build locale assets. Advantages to use:
- component approach - merge locales from different application volumes or its components or from external libraries
- acceleration - minimize download time and amount of traffic by loading only the required locale
- configuration flexibility - locales sources may be described by the
require/importin the js source (due to deep webpack integration) or as simple glob path pattern in the wepback configuration file
- developing flexibility - immediately locale change updatetion in the application under webpack dev server (due to deep webpack integration)
- make structure flatten - make struct entries keys flatten (if needed) for easier to use the branch path as a string key
This is locale data build tool and it is independent from internationalization library or framework which may be react-intl or i18n-js or yui-intl or angular-dynamic-locale or any your favorite internationalization system. A link to a running
npm install --save intl-webpack-plugin
This example is minimal configuration to merge json to single asset:
module:rules:test: /\.$/iuse:IntlPlugin'yaml-loader'plugins:search: './src/**/*.intl'
The name of file is locale identificator but this may be changed to file extestion by configure using grouping technique
In order to require the builded locale asset need at least one file which name matches name of locale. To change this, it is need to configure the webpack module loading rules and grouping technique as need.
The locale file may be empty (or an empty hash for json format) because actually loaded asset will be populated with other joined sources of current locale.
These imported variables contain public urls of assets with locale assembly.
In order to involve files into locale assebly, files must be required by
import somewhere in code or described by pattern in
param of plugin configuration.
Refer to demonstration application with internationalization for more details about how to configure application and how to import library with support internationalization.
This section is for component library developers.
Refer to the demonstration component library example which demonstrates how to create library with support of internationalization and documentation how to integrate it in application.
To join locales from library package to application locale assets need to:
- describe in documentation locale structure organization and format to load, and enumerate supported locales - this required to configure this webpack plugin with loaders
- export file which each locale file is required by calling
requirefunction or by
import, describe how to require it in code
- and/or another way is to describe path pattern to locale files and how to configure plugin to search and prefetch
So application developers may identify how to integrate location assets to application and choose way how to configure plugin to join library package locales with application locales. More about format and structure organization described in component approach
Library package locales may be joined by define pattern in
option or by importing module from library in which library locales enumerated
require function or
IntlPlugin typically created at the webpack configuration file and waits hash of configuration options as its creation param:
var IntlPlugin = ;var intlPlugin =search: 'glob' || 'globs'...skip: 'substr' || /regexp/ || 'substr' /regex/ ...flattenLowness: 1flattenDepth: 2...loaderOptions;
search- glob pattern or pattern array to find and prefetch see glob module for reference
skip- substring or regular expression or array to skip some from the searched results
flattenLowness- the level from which struct will be flatten. The default value of
flattenLownessis 1 which reserved for top level key locale name, and any another purpose if it does not intersect with the names of locales.
flattenDepth- flattenization depth level. The default value
flattenDepthis not defined which mean depth does not limited and works through the depth, to disable flattenization specify value 1 on
group- the default
grouploader option, the default value is '[name]' to join in groups by file name which is equal to the name of the locale
nameloader option (define pattern for asset file name)
search param is like multi-require with glob patterns.
Only files that required by
require function in code
will be loaded in that case.
Any file that do not match to
skip param and
match to loader section in webpack config and is required in code
import will be loaded and merged anyway.
loader() method includes intl loader into loader chain.
var IntlPlugin = ;var theIntl = ...module:loaders:theIntl// some more pre loadersplugins:theIntl
Preliminary loaders must be applied before intl loader. This means that intl loader must be final loader in loaders chain.
Loader function waits hash of configuration options as its param. Default values of loader may be specified in plugin configuration described above.
group- devides files into separated assets by specifying groping pattern. May include template placeholders described below in groupping section.
name- specifies destination asset file name. String value supportive loader template interpolation placeholders.
Configuration options specified directly in call
override same values specified as default in plugin configuration.
loader() function may be invoked as class function if only one plugin
instance is passed to config. Therefore it is better to use object form
instead of class form:
var theIntl = ...loaders:// this form valid only for single plugin instance:IntlPlugin// to avoid problems better to use always object form:theIntl
- demonstration application - with internationalization as example how to configure application and how to import library support internationalization.
- demonstration component library - example for more details about how to create library with support internationalization.
- join-webpack-plugin - to join sources by user defined method.
- merge-webpack-plugin - plugin to merge json files to asset (or aseets with grouping)