# @transferwise/translation-helper

> A translation helper mainly used in Webpack context.

Latest version **0.1.2** (published 2017-11-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install @transferwise/translation-helper
pnpm add @transferwise/translation-helper
yarn add @transferwise/translation-helper
bun add @transferwise/translation-helper
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.2 |
| Published | 2017-11-16 |
| First published | 2017-11-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | TransferWise |
| Maintainers | timotheehub, wilson.jimenez, emercer, melvintiong-tw, hecekgl, karlest, harshsinha, banerjee.argha, saturnin, codewhisperer, sofiia.horishna, stevepole, iankovskii-tw, ilhantw, igor.tryus, andrii.khrystian, indrekr, antondozortsev, vahurh, tw-jenkins, skywritergr, vambotw, ttqin, timasjov, tankenstein, srumjanttw, vladyslav.chornobai, tburko, offllne, ofthehours, omarduarte, petru.dimulescu, phildobsontw, neljandik, sergeil, mutyonok, mihkel.noges, martin.magar, massimo-tw, kyrylo.novotarskyi, kdelemme, kkowalski-tw, hwendel, dan.oak, craastad, daves125125, dimkagfx, daedelus-j, cassio.greco, coolsebz, ariapar, bukharih, andras.toth.tw, aleksbocharov, jerome.lapostolet, keyvanakbary, chujimmy, nabaroa, stephantransferwise, cat2608, kstamtw, oliverviljamaa, adriendog, _bengro, tw-circleci |
| Keywords | webpack, translation, i18n, messages |

## Links

- npm: https://www.npmjs.com/package/@transferwise/translation-helper
- Repository: https://github.com/transferwise/translation-helper
- Homepage: https://github.com/transferwise/translation-helper#readme
- Issues: https://github.com/transferwise/translation-helper/issues
- npm.io page: https://npm.io/package/@transferwise/translation-helper

## Dependencies (1)

- [release-to-github-with-changelog](https://npm.io/package/release-to-github-with-changelog.md) ^1.1.5

## Alternatives

- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads

## Recent versions

- 0.1.2 (latest) — 2017-11-16
- 0.1.0 — 2017-11-15

## README

# Translation helper

[![npm](https://img.shields.io/npm/v/@transferwise/translation-helper.svg)](https://www.npmjs.com/package/@transferwise/translation-helper)
[![GitHub release](https://img.shields.io/github/release/transferwise/translation-helper.svg)](https://github.com/transferwise/translation-helper/releases)
[![CircleCI](https://img.shields.io/circleci/project/github/transferwise/translation-helper/master.svg)](https://circleci.com/gh/transferwise/translation-helper)
[![npm](https://img.shields.io/npm/l/translation-helper.svg)](https://github.com/transferwise/translation-helper/blob/master/LICENSE)

## 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

```javascript
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`     	|

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

```javascript
import translations from 'translations';

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

## Example with files

With the following files:

```bash
.
├── 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:
```json
{
  "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:

```bash
.
├── 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](https://github.com/transferwise/translation-helper/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`.
1. Develop
1. **Bump version number in `package.json` according to [semver](http://semver.org/) and add an item that a release will be based on to `CHANGELOG.md`**.
1. Submit your pull request from a feature branch and get code reviewed.
1. If the pull request is approved and the [CircleCI build](https://circleci.com/gh/transferwise/translation-helper) passes, you will be able to merge with rebase.
1. Code will automatically be released to [GitHub](https://github.com/transferwise/translation-helper/releases) and published to [npm](https://www.npmjs.com/package/@transferwise/translation-helper) according to the version specified in the changelog and `package.json`.

---
_Source: https://npm.io/package/@transferwise/translation-helper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._