@zakkudo/translate-webpack-plugin

A webpack plugin for scanning javscript files to build translation mappings in json automatically.

Why use this?

• Automated code splittiing
• You no longer have to manage hierarchies of translations
• Designed for architectures leveraging dynamic imports, allowing splitting of the translations based off of file structure
• Templates are automatically generated for the translators where they only need to fill in the blanks
• The translations are annoted if they are new or unused as well as the file names and line numbers of usages
• Easy auditing for missing or non-updated translation strings with never running your application or enlisting QA
• Any string wrapped in __() or __n() or __p() or __np(), will be picked up as a translatable making usage extremely easy for developers
• Works similarly to the venerable gettext. Any translation strategies that work for that library work for this library. translatable making usage extremely easy for developers

What does it do?

• It searches your source code for translatable strings and aggregates them
• It writes human-centric translation templates in json5 showing usages, new strings and no longer used strings
• It generates developer-centric optimized json templates, stripping away any unused strings and metadata

Install

1# Install using npm
2npm install @zakkudo/translate-webpack-plugin

1# Install using yarn
2yarn add @zakkudo/translate-webpack-plugin

Setup

1. Wrap strings you want to be translated in __('text') or __n('singlular', 'plural', number) using a library like @zakkudo/translator
2. Add the plugin to webpack

1const TranslateWebpackPlugin = require('@zakkudo/translate-webpack-plugin');
2
3module.exports = {
4    plugins: [
5        new TranslateWebpackPlugin({
6            // Analyzes all javscript files in the src directory, which is a good initial value
7            files: 'src/**/*.js',
8            // Use verbose output to see what files are parsed, what keys are extracted, and where they are being written to
9            debug: true,
10            // You do not need to add your default language (which for most people will be English)
11            locales: ['fr'],
12            // Consolidate all of the optimized localizations into `src/.locale`, good as an initial configuration
13            target: 'src'
14        })
15    ]
16};

3. Add .locales to your .gitignore so it isn't commited. It is a dynamic source file that has no value being added to a repository. Its existance in the src directory is simply to facilitate importing it.
4. Add find src -name '.locales' | xargs rm -r to your clean scripts for an easy way to remove the auto generated src/.locales from your source code
5. Import locales into your source code from the src/.locales folder so you can merge it into the lookup of @zakkudo/translator. It is plain old json with the untranslated and unexisting values optimized out.
6. Have your localization team use the files from locales (without a period.) It's annoted with information about new, unused, and existing usages of the translations to help them audit what needs updating.

You'll end up with a file structure similar to below.

File Structure
├── locales <- For your translators
│   ├── en.json
│   └── fr.json
└── src
    ├── .locales <- For your developers
    │   ├── en.json
    │   └── fr.json
    └── pages
        ├── About
        │   └── index.js
        └── Search
            └── index.js

Where locales/fr.json will look like this for use by your translators:

1{
2    "About": {
3        // NEW
4        // src/pages/AboutPage/index.js:14
5        "default": ""
6    },
7    "Search": {
8        // UNUSED
9        "default": "French translation",
10        // UNUSED
11        "menuitem": "French translation"
12    },
13    "There is one user": {
14        // src/pages/AboutPage/index.js:40
15        "default": {"1":"French translation", "2":"French translation"},
16    },
17    "Welcome to the about page!": {
18        // src/pages/AboutPage/index.js:38
19        "default": "French translation"
20    }
21}

And the optimized src/.locales/fr.json will look like this for use by your developers:

1{
2    "There is one user": {"one":"French translation", "other":"French translation"},
3    "Welcome to the about page!": "French translation"
4}

Your developers will use the translation similarly to below:

1import Translator from '@zakkudo/translator';
2import fr from 'src/.locales/fr.json';
3const translator = new Translator();
4const {__, __n} = translator;
5const language = navigator.language.split('-')[0];
6
7translator.setLocalization('fr', fr);
8translator.setLocale(language);
9
10document.title = __('About');
11document.body.innerHTML = __n('There is one user', 'There are %d users', 2);

Examples

Configure the plugin to build a single .locales directory

1module.exports = {
2    plugins: [
3        new TranslateWebpackPlugin({
4            files: 'src/**/*.js',
5            locales: ['es', 'fr'],
6            target: 'src'
7        });
8    ]
9};

File Structure
├── locales <- For your translators. Contains translations for everything
│   ├── es.json
│   └── fr.json
└── src
    ├── Application.js
    ├── .locales <- For your developers. Contains translations for everything
    │   ├── es.json
    │   └── fr.json
    └── pages
        ├── About
        │   └── index.js
        └── Search
            └── index.js

Configure the plugin for a split .locales directory

1module.exports = {
2    plugins: [
3        new TranslateWebpackPlugin({
4            files: 'src/**/*.js',
5            locales: ['es', 'fr'],
6            target: 'src/pages/*'
7        })
8    ]
9};

File Structure
├── locales <- For your translators. Contains translations for everything
│   ├── es.json
│   └── fr.json
└── src
    ├── Application.js
    └── pages
        ├── About
        │   ├── .locales <- For your developers. Contains translations for `Application.js` and `About/index.js`
        │   │   ├── es.json
        │   │   └── fr.json
        │   └── index.js
        └── Search
            ├── .locales <- For your developers. Contains translations for `Application.js` and `Search/index.js`
            │   ├── es.json
            │   └── fr.json
            └── index.js

Also see

• @zakkudo/translation-static-analyzer for the generic library that this package thinly wraps
• @zakkudo/translator is a library that can read the localization with no fuss and apply the translations.
• Polymer 3 Starter Project is an example project using this library.

API

@zakkudo/translate-webpack-plugin~TranslateWebpackPlugin ⏏

Plugin for analyzing javascript source files, extracting the translations, and converting them into localization templates.

Kind: Exported class

• ~TranslateWebpackPlugin
  • new TranslateWebpackPlugin(options)
  • .apply(compiler)

new TranslateWebpackPlugin(options)

Param	Type	Default	Description
options	Object		The modifiers for how the analyzer is run
options.files	String		A glob pattern of the files to pull translations from
[options.debug]	Boolean	false	Show debugging information in the console
[options.locales]	Array.<String>	[]	The locales to generate (eg fr, ja_JP, en)
[options.templates]	String		The location to store the translator translatable templates for each language. Defaults to making a locales directory in the current working directory
[options.target]	String		Where to write the final translations, which can be split between multiple directories for modularity. If there are no targets, no .locales directory will be generated anywhere.

translateWebpackPlugin.apply(compiler)

Method called by the webpack plugin system during watch to inform the plugin when some files have been updated.

Kind: instance method of TranslateWebpackPlugin

Param	Type	Description
compiler	Object	The webpack compiler object