gulp-json-angular-translate/README.md

Gulp plugin to convert json files to angular-translate js files

# gulp-json-angular-translate

> Converts json files to [angular-translate](https://github.com/angular-translate/angular-translate) config javascript files.

> Gulp version of the [grunt-json-angular-translate](https://github.com/shahata/grunt-json-angular-translate) plugin

## Getting Started
This plugin requires [Gulp](http://gulpjs.com/).

```shell
npm install gulp-json-angular-translate --save-dev
```

Once installed, it's available under `gulp-json-angular-translate`:

```js
var jsonAngularTranslate = require('gulp-json-angular-translate');
```

## Usage

```js
gulp.src('*/**/locale/*.json')
  .pipe(jsonAngularTranslate({
    moduleName: 'translations',
    extractLanguage: /..(?=\.[^.]*$)/,
    hasPreferredLanguage: true,
    createNestedKeys: true
  }))
  .pipe(gulp.dest('.tmp/scripts'))
})
```

## Options

### moduleName
Type: `String`
Default value: `translations`

The module name to use in the `angular.module` calls.

### extractLanguage
Type: `RegExp|Function`
Default value: `/..(?=\.[^.]*$)/` (last two characters before the last dot)

A regular expression or a function that returns the processed file's language according to its file path.

### hasPreferredLanguage
Type: `Boolean`
Default value: `true`

Whether to set the language and preferred language in config file. Relevant only in angular-translate `1.*`.

### createNestedKeys
Type: `Boolean`
Default value: `true`

Whether to create a nested output from dot separated keys.

#### Source json
```
{
  "My.First.Key": "..."
}
```
#### Outputs
```
{
  'My': {
    'First': {
      'Key': '...'
    }
  }
}
```
Set this option to false if you use your source language string as the key.

#### createNestedKeys: false, Outputs
```
{
  'My.First.Key': '...'
}
```

## Usage Examples

### Default Options
Convert all .json files in `app/scripts/locale` to angular-translate config files in `.tmp/scripts/locale`.

```js
gulp.src('*.json', {cwd: 'app/scripts/locale'})
  .pipe(jsonAngularTranslate())
  .pipe(gulp.dest('.tmp/scripts/locale'));
```

So `app/scripts/locale/messages_ru.js` with contents:

```js
{
  "key1": "value1",
  "key2.subKey1": "value2",
  "key2.subKey2": "value3"
}
```

Will be converted to `.tmp/scripts/locale/messages_ru.js` with contents:

```js
'use strict';

try {
  angular.module('translations');
} catch (e) {
  angular.module('translations', ['pascalprecht.translate']);
}

angular.module('translations').config(['$translateProvider', function ($translateProvider) {
  var translations = {
    'key1': 'value1',
    'key2': {
      'subKey1': 'value2',
      'subKey2': 'value3'
    }
  };
  $translateProvider.translations('ru', translations);
  $translateProvider.translations(translations);
  $translateProvider.preferredLanguage('ru');
}]);
```

### Custom Options
In this example, we convert all .json files in `app/scripts/locale` to angular-translate config files in `.tmp/scripts/locale` with custom `moduleName`. Thanks to the custom `extractLanguage` file's language code will be extracted from the first two characters in the file name, so filepath `app/scripts/locale/he_messages.json` will get language code `he`.

```js
gulp.src('*.json', {cwd: 'app/scripts/locale'})
  .pipe(jsonAngularTranslate({
    moduleName: 'myAppTranslations',
    extractLanguage: function (filepath) {
      return filepath.split('/').reverse()[0].slice(2);
    }
  }))
  .pipe(gulp.dest('.tmp/scripts/locale'));
})
```

## Contributing

Unit tests mandatory, run them with `npm test` (uses mocha).