@transferwise/translation-helper

Translation helper

Description

This is a translation helper for Webpack. It is used to create specific bundles for each of your supported languages in addition to the bundle containing all the languages, automatically. This allows us to serve only the messages we need for a certain locale to the customers, decreasing the payload size.

The setup is complicated, but after that, even with new language additions, no modifications are needed.

Usage

Installation

npm install --save-dev @transferwise/translation-helper

Usage in Webpack config

import path from 'path';
import TranslationHelper from '@transferwise/translation-helper'; // 1


const messagesPath = path.join(__dirname, 'translations'); // 2

const translationHelper = new TranslationHelper({
  messagesPath, // required
  messagesFileNameBase: 'my-messages', // default: 'messages'
  messagesExtension: 'myjson', // default: 'json'
}); // 3

translationHelper.init(); // 4

module.exports = translationHelper.getLanguageCodesWithAll().map(code => ({ // 5
  entry: ...,
  output: {
    path: path.join(__dirname, 'dist', translationHelper.getPathForCode(code)), // 6
    filename: `output${translationHelper.getSuffixForCode(code)}.js`, // 7
  },
  module: ...,
  resolve: {
    alias: {
      translations: path.join(messagesPath, translationHelper.getMessagesFileNameForCode(code)), // 8
    },
  },
}));

1. Import the TranslationHelper class
2. Set the absolute path for the directory containing all your messages files
3. Instantiate a TranslationHelper with:

Option	Description	Default
messagesPath	Absolute path for the directory containing all your messages files	* required
messagesFileNameBase	File name base for messages files (your source messages file name without the extension)	messages
messagesExtension	Extension for messages files	json

1. Initialize the helper (this creates a messages file containing messages from all languages, under respective language code properties).
2. Export an array of configs to build multiple bundles by getting all languages from the messages directory
3. Get path for language. This is necessary to build the bundle containing all translations in the same directory, but language bundles in i18n directory.
4. Get suffix for language. This is necessary to export the bundle containing all translations as output.js instead of output.all.js.
5. Use an alias to be able to import translations from 'translations'; in your translations config.
6. Add support for the bundle containing all translations and language bundles in your translations config. For example, in angular with angular-translate:

import translations from 'translations';

...
$translateProvider.translations(languageCode, translations[languageCode] || translations);
...

Example with files

With the following files:

.
├── node_modules
├── translations
│   ├── messages.json
│   ├── messages.en.json
│   ├── messages.en-US.json
│   └── messages.it.json
├── package.json
└── webpack.config.js

• messagesPath would be path.join(__dirname, 'translations')

• messagesFileNameBase would be 'messages' (default)

• messagesExtension would be 'json' (default)

• translationHelper.init() would create a messages.all.json file in translations with the following structure:

{
  "en": {
    ...
  },
  "en-US": {
    ...
  },
  "it": {
    ...
  }
}

• translationHelper.getLanguageCodesWithAll() would return ['all', 'en', 'en-US', 'it'], so in total, we would create four bundles
• When imported from the code, translations would be the all format shown above with translations objects as values of the language codes in case of the all-inclusive bundle, or just the translations object in case of language bundles
• When Webpack config output.path is specified as path.join(__dirname, 'dist', translationHelper.getPathForCode(code)) and the output.filename is `output${tran`slationHelper.getSuffixForCode(code)}.js`, we would get the following end result:

.
├── dist
│   ├── output.js
│   ├── i18n
│   │   ├── output.en.js
│   │   ├── output.en-US.js
│   │   └── output.it.js
├── node_modules
├── translations
│   ├── messages.json
│   ├── messages.all.json # not to be committed
│   ├── messages.en.json
│   ├── messages.en-US.json
│   ├── messages.it.json
├── package.json
└── webpack.config.js

Future work

Ideally, this should be a Webpack plugin, allowing us to decrease the number of contact points.

For features and bugs, feel free to add issues or contribute.

Contributing

1. Run tests in watch mode with npm run test:watch. For a single-run check with ESLint, run npm test.
2. Develop
3. Bump version number in package.json according to semver and add an item that a release will be based on to CHANGELOG.md.
4. Submit your pull request from a feature branch and get code reviewed.
5. If the pull request is approved and the CircleCI build passes, you will be able to merge with rebase.
6. Code will automatically be released to GitHub and published to npm according to the version specified in the changelog and package.json.