/ng-translation

Fast, Easy and Dynamic translation for AngularJS

Primary LanguageJavaScriptMIT LicenseMIT

#ngTranslation
NPM version Test coverage Dependency Status License

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

##Table of contents:

##Get Started (1) You can install ng-translation using 3 different ways:

  • clone & build this repository
  • Bower: by running $ bower install ng-translation from your terminal
  • via npm: 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:

<!doctype html>
<html ng-app="myApp">
<head>
   
</head>
<body>
    ...
    <script src="//ajax.googleapis.com/ajax/libs/angularjs/1.3.0/angular.min.js"></script>
    <script src="bower_components/js/ng-translation.min.js"></script>
    ...
    <script>
        angular.module('myApp', ['ng-translation'])
          .controller('MainCtrl', function($scope) {
            //...
          });
    </script>
    ...
</body>
</html>

##Example Quick example:
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)

{
  "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:

    <!-- simple usage example -->
    <h3>{{ 'title' | translate }}</h3>
    <h4>{{ 'description.text'  | translate }}</h4>
    <p>{{ 'button' | translate }}</p>

    <!-- directive example -->
    <p ng-translate="'message'"></p>
    <p ng-translate="es('message')"></p>

    <!-- bind to model example -->
    <table style="border:1px solid red">
        <tr>
            <td>User Details:</td>
        </tr>
        <tr>
            <td>{{ 'message' | translate: this }}</td>
        </tr>
        <tr>
            Change user details:
        </tr>
        <tr>
            <td>name: <input ng-model="user.name" type="text"/> </td>
        </tr>
        <tr>
            <td>password: <input ng-model="user.password" type="text"/> </td>
        </tr>
    </table>

To learn more, Read the documentation...

##Configuration ngTranlation configuration options, see below:

###setBaseUrl Set base url for static/languages files directory.
Aliases: setDirectory

angular.module('app', ['ng-translation'])
  .config(['ngTranslationProvider', function(ngTranslationProvider) {
    ngTranslationProvider
      .setDirectory('/ng-translation/demo/languages');
  }]);

###langsFiles Set languages files as a key value pairs.

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.

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.

angular.module('app', ['ng-translation'])
  .config(['ngTranslationProvider', function(ngTranslationProvider) {
    ngTranslationProvider
      .addLangFile({
        en: 'filename.json'
      });
  }]);

###setFilesSuffix Set global suffix to all files.

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.

angular.module('app', ['ng-translation'])
  .config(['ngTranslationProvider', function(ngTranslationProvider) {
    ngTranslationProvider
      .fallbackLanguage('en');
  }]);

##API The returns API, see below:

###configuration The expose configuration

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}

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}

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}

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}

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).
<p>{{ 'message' | translate }}</p>
<p>{{ 'message.nested' | translate }}</p>
<!-- note: 'key' is a property on the scope -->
<p>{{ key | translate }}</p>
  • from specific file - pass a key, and fileName(language), and get the value from this file.
<p>{{ 'message' | translate: 'en' }}<p>
<p>{{ 'message.nested' | translate: 'de' }}<p>
<!-- note: 'key' and `lang` are a properties on the scope -->
<p>{{ key | translate: lang }}<p>
  • 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 }}
$scope.user = { name: 'Ariel M.' }
$scope.property = 'value';
<!-- note: user is a property on the scope, so if the real value on the file is:
`hello {{ name }}, wanna login?`
the result will be: `hello Ariel M., wanna login ?` -->
<p>{{ 'user.message' | translate: user }}</p>
<!-- note: if you want to use directly properties on $scope, use the `this` keyword,
(every $scope, have the own `this` property that point to him self) -->
<p>{{ 'message' | translate: this }}</p>
  • interpolate from other file - if you want the same interpolation behavior, but get the value from specific file.
    Usage: {{ key | translate: lang: object }}
<p>{{ 'user.message' | translate: 'de': user }}</p>
<!-- note: 'key' and `lang` are a properties on the scope -->
<p>{{ key | translate: lang: this }}</p>

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

  • get the value from the usedFile(prefered language, .use).
<p ng-translate="'message'"></p>
<!-- note: 'key' is a property on the scope -->
<p ng-translate="key"></p>
  • get the value from specific file(specific language).
<!-- note: `en` interpolate as a string -->
<p ng-translate="en('message')"></p>
<!-- note: 'key' is a property on the scope -->
<p ng-translate="de(key)"></p>