Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/a8m/ng-translation

Fast, Easy and Dynamic translation for AngularJS
https://github.com/a8m/ng-translation

Last synced: 6 months ago
JSON representation

Fast, Easy and Dynamic translation for AngularJS

Awesome Lists containing this project

README 

          
#ngTranslation  

[![NPM version][npm-image]][npm-url]

[![Test coverage][coveralls-image]][coveralls-url]

[![Dependency Status][david-image]][david-url]

[![License][license-image]][license-url]

> Fast, Easy and Dynamic translation for AngularJS. **v0.0.3**



##Table of contents:

- [Get Started](#get-started)

- [Example](#example)

- [Development](#development)

- [ngTranslationProvider](#ngtranslationprovider)

  - [Configuration](#configuration)

    - [setBaseUrl](#setbaseurl)

    - [langsFiles](#langsfiles)

    - [langsValues](#langsvalues)

    - [addLangFile](#addlangfile)

    - [setFilesSuffix](#setfilessuffix)

    - [fallbackLanguage](#fallbacklanguage)

  - [API](#api)

    - [configuration](#configuration1)

    - [get](#get)

    - [getAll](#getall)

    - [getUsed](#getused)

    - [init](init)

    - [use](#use)

- [ngTranslationFilter](#ngtranslationfilter)

- [ngTranslationDirective](#ngtranslationdirective)



##Get Started

**(1)** You can install ng-translation using 3 different ways:  

  - clone & [build](#developing) this repository

  - **[Bower](http://bower.io/)**: by running `$ bower install ng-translation` from your terminal

  - via **[npm](https://www.npmjs.org/)**: by running `$ npm install ng-translation` from your terminal  



**(2)** Include `ng-translation.js` (or `ng-translation.min.js`) in your `index.html`, after including Angular itself.    



**(3)** Add `'ng-translation'` to your main module's list of dependencies.    



When you're done, your setup should look similar to the following:



```html



   



    ...

    

    

    ...

    

        angular.module('myApp', ['ng-translation'])

          .controller('MainCtrl', function($scope) {

            //...

          });

    

    ...



```

##Example

**Quick example:**  

**JS:**  

```js

/**

 * Directory structure

 * __ __ __ __ __ __

 * | - dist          |

 * |   - assets      |

 * |     - static    |

 * |__ __ __ __ __ __|

 */

//AngularJS app

angular.module('app', ['ng-translation'])

  .config(['ngTranslationProvider', function(ngTranslationProvider) {

    ngTranslationProvider

      .setDirectory('/dist/assets/static')

      .setFilesSuffix('.json')

      .langsFiles({

        en: 'en',

        de: 'de',

        es: 'es'

      })

      .fallbackLanguage('en')

  }])

  .run(['ngTranslation', '$location'], function(ngTranslation, $location) {

    ngTranslation.use(

        $location.search().lang

      );

  });

```

**JSON:** (one file for example)    

```json

{

  "title": "Wählen Sie eine Vorlage, um zu beginnen.",

  "description": {

    "text": "Hunderte vollständig anpassbarer HTML5-Templates in jeder Kategorie verfügbar."

  },

  "button": "Anmelden",

  "message": "Hallo {{user.name}}, Uw wachtwoord is: {{user.password}}"

}

```

**HTML:**

```html

    

    
{{ 'title' | translate }}


    
{{ 'description.text'  | translate }}


    
{{ 'button' | translate }}



    

    


    



    

    

        

            User Details:

        

        

            {{ 'message' | translate: this }}

        

        

            Change user details:

        

        

            name:  

        

        

            password:  

        

    

```



**To learn more, Read the documentation...**



##Configuration

ngTranlation configuration options, **see below:**



###setBaseUrl

Set base url for static/languages files directory.  

**Aliases:** `setDirectory`

```js

angular.module('app', ['ng-translation'])

  .config(['ngTranslationProvider', function(ngTranslationProvider) {

    ngTranslationProvider

      .setDirectory('/ng-translation/demo/languages');

  }]);

```

###langsFiles

Set languages files as a key value pairs.  

```js

angular.module('app', ['ng-translation'])

  .config(['ngTranslationProvider', function(ngTranslationProvider) {

    ngTranslationProvider

      .setDirectory('/ng-translation/demo/languages')

      .langsFiles({

        en: 'en.json',

        de: 'de.json',

        es: 'es.json'

      });

  }]);

```

###langsValues

Set array of values as a languages files.  

```js

angular.module('app', ['ng-translation'])

  .value({

    en: { foo: 'Hello' },

    de: { foo: 'Hallo' }

  })

  .config(['ngTranslationProvider', function(ngTranslationProvider) {

    ngTranslationProvider

      .langsValues([

        'en',

        'de'

      ]);

  }]);

```

###addLangFile

Add a single language file.  

```js

angular.module('app', ['ng-translation'])

  .config(['ngTranslationProvider', function(ngTranslationProvider) {

    ngTranslationProvider

      .addLangFile({

        en: 'filename.json'

      });

  }]);

```

###setFilesSuffix

Set global suffix to all files.  

```js

angular.module('app', ['ng-translation'])

  .config(['ngTranslationProvider', function(ngTranslationProvider) {

    ngTranslationProvider

      .setFilesSuffix('-static.json')

      .langsFiles({

        en: 'en', // <== en-static.json

        de: 'de',

        es: 'es'

      });

  }]);

```

###fallbackLanguage

Set fallback language. 

```js

angular.module('app', ['ng-translation'])

  .config(['ngTranslationProvider', function(ngTranslationProvider) {

    ngTranslationProvider

      .fallbackLanguage('en');

  }]);

```

##API

The returns API, **see below:**



###configuration

The expose configuration

```js

angular.module('app', ['ng-translation'])

  .controller('MainCtrl', function(ngTranslation) {

    console.log(ngTranslation.configuration);

    //{ baseUrl: "/ng-translation/demo/languages", suffix: ".json", langsFiles: Obje... }

  });

```

###get

Get specific file by name.  

**Usage:** `ngTranslation.get({String})`

**Returns:** file `{Object}`

```js

angular.module('app', ['ng-translation'])

  .controller('MainCtrl', function(ngTranslation) {

    $scope.getByName = function(name) {

      return ngTranslation.get(name); 

      //{title: "Select a Template", message: "Hello {{ user.name... }

    };

  });

```

###getAll

Get all files(the staticFilesContainer)

**Usage:** `ngTranslation.getAll()`

**Returns:** files `{Object}`

```js

angular.module('app', ['ng-translation'])

  .controller('MainCtrl', function(ngTranslation) {

    $scope.getAll = function() {

      return ngTranslation.getAll(); 

      //{ en: Object, de: Object, es: Obje... }

    };

  });

```

###getUsed

Get the current used file || fallback file  

**Usage:** `ngTranslation.getUsed()`  

**Returns:** file `{Object}`

```js

angular.module('app', ['ng-translation'])

  .controller('MainCtrl', function(ngTranslation) {

    $scope.getUsed = function() {

      return ngTranslation.getUsed(); 

       //{title: "Select a Template", message: "Hello {{ user.name... }

    };

  });

```

###init

`@private` function.  



###use

Use specific language.(prefered language)  

**Usage:** `ngTranslation.use({String})`  

**Returns:** `{Boolean}`

```js

angular.module('app', ['ng-translation'])

  .run(function($location, ngTranslation) {

    ngTranslation.use(

      $location.search().lang //e.g: "de", "en"

    );

  });

```

##ngTranslationFilter

There's a 4 ways to use the `translate` filter.  

* simple - pass a key, and get the value from the **usedFile**(prefered language, `.use`).

```html

{{ 'message' | translate }}


{{ 'message.nested' | translate }}



{{ key | translate }}


```

* from specific file - pass a key, and fileName(language), and get the value from `this` file.

```html

{{ 'message' | translate: 'en' }}


{{ 'message.nested' | translate: 'de' }}



{{ key | translate: lang }}


```

* interpolate - there's a situation, that you want to store an angular expression as a value.  

**e.g**: `'this is string that {{ foo }}, {{ bar.baz }} need to interpolate.'`  

**Usage:** `{{ key | translate: object }}`  

```js

$scope.user = { name: 'Ariel M.' }

$scope.property = 'value';

```

```html



{{ 'user.message' | translate: user }}



{{ 'message' | translate: this }}


```

* interpolate from other file - if you want the same interpolation behavior, but get the value 

from specific file.  

**Usage:** `{{ key | translate: lang: object }}`  

```html

{{ 'user.message' | translate: 'de': user }}



{{ key | translate: lang: this }}


```

##ngTranslationDirective

There's a 2 ways to use the `ngTranslate` directive.

* get the value from the **usedFile**(prefered language, `.use`).

```html






```

* get the value from specific file(specific language).

```html








```



[npm-image]: https://img.shields.io/npm/v/ng-translation.svg?style=flat-square

[npm-url]: https://npmjs.org/package/ng-translation

[coveralls-image]: https://img.shields.io/coveralls/a8m/ng-translation.svg?style=flat-square

[coveralls-url]: https://coveralls.io/r/a8m/ng-translation

[david-image]: http://img.shields.io/david/a8m/ng-translation.svg?style=flat-square

[david-url]: https://david-dm.org/a8m/ng-translation

[license-image]: http://img.shields.io/npm/l/ng-translation.svg?style=flat-square

[license-url]: LICENSE