Improve this Doc

# `ngMessageFormat`

## Installation

First, get the file:

- Google CDN e.g.

      "//ajax.googleapis.com/ajax/libs/angularjs/X.Y.Z/angular-message-format.js"

- NPM e.g.

      npm install --save angular-message-format@X.Y.Z

  or

      yarn add angular-message-format@X.Y.Z

- Bower e.g.

      bower install angular-message-format#X.Y.Z

- code.angularjs.org (discouraged for production use) e.g.

      "//code.angularjs.org/X.Y.Z/angular-message-format.js"

where X.Y.Z is the AngularJS version you are running.

Then, include `angular-message-format.js` in your HTML:

    <script src="path/to/angular.js"></script>
    <script src="path/to/angular-message-format.js"></script>

Finally, load the module in your application by adding it as a dependent module:

    angular.module('app', ['ngMessageFormat']);

With that you're ready to get started!

## What is ngMessageFormat?

The ngMessageFormat module extends the AngularJS `$interpolate` service with a syntax for handling pluralization and gender specific messages, which is based on the ICU MessageFormat syntax.

See the design doc for more information.

## Examples

### Gender

This example uses the "select" keyword to specify the message based on gender.

    <div ng-controller="AppController">
      Select Recipient:<br>
         <select ng-model="recipient" ng-options="person as person.name for person in recipients">
         </select>
         <p>{{recipient.gender, select,
                   male {{{recipient.name}} unwrapped his gift. }
                   female {{{recipient.name}} unwrapped her gift. }
                   other {{{recipient.name}} unwrapped their gift. }
         }}</p>
    </div>

    function Person(name, gender) {
      this.name = name;
      this.gender = gender;
    }

    var alice   = new Person('Alice', 'female'),
        bob     = new Person('Bob', 'male'),
        ashley = new Person('Ashley', '');

    angular.module('msgFmtExample', ['ngMessageFormat'])
      .controller('AppController', ['$scope', function($scope) {
          $scope.recipients = [alice, bob, ashley];
          $scope.recipient = $scope.recipients[0];
        }]);

### Plural

This example shows how the "plural" keyword is used to account for a variable number of entities. The "#" variable holds the current number and can be embedded in the message.

Note that "=1" takes precedence over "one".

The example also shows the "offset" keyword, which allows you to offset the value of the "#" variable.

    <div ng-controller="AppController">
     <button ng-click="recipients.pop()" id="decreaseRecipients">decreaseRecipients</button><br>
     Select recipients:<br>
     <select multiple size=5 ng-model="recipients" ng-options="person as person.name for person in people">
     </select><br>
      <p>{{recipients.length, plural, offset:1
              =0    {{{sender.name}} gave no gifts (\#=#)}
              =1    {{{sender.name}} gave a gift to {{recipients[0].name}} (\#=#)}
              one   {{{sender.name}} gave {{recipients[0].name}} and one other person a gift (\#=#)}
              other {{{sender.name}} gave {{recipients[0].name}} and # other people a gift (\#=#)}
            }}</p>
    </div>

    function Person(name, gender) {
      this.name = name;
      this.gender = gender;
    }

    var alice   = new Person('Alice', 'female'),
        bob     = new Person('Bob', 'male'),
        sarah     = new Person('Sarah', 'female'),
        harry   = new Person('Harry Potter', 'male'),
        ashley   = new Person('Ashley', '');

    angular.module('msgFmtExample', ['ngMessageFormat'])
      .controller('AppController', ['$scope', function($scope) {
          $scope.people = [alice, bob, sarah, ashley];
          $scope.recipients = [alice, bob, sarah];
          $scope.sender = harry;
        }]);

    describe('MessageFormat plural', function() {

      it('should pluralize initial values', function() {
        var messageElem = element(by.binding('recipients.length')),
            decreaseRecipientsBtn = element(by.id('decreaseRecipients'));

        expect(messageElem.getText()).toEqual('Harry Potter gave Alice and 2 other people a gift (#=2)');
        decreaseRecipientsBtn.click();
        expect(messageElem.getText()).toEqual('Harry Potter gave Alice and one other person a gift (#=1)');
        decreaseRecipientsBtn.click();
        expect(messageElem.getText()).toEqual('Harry Potter gave a gift to Alice (#=0)');
        decreaseRecipientsBtn.click();
        expect(messageElem.getText()).toEqual('Harry Potter gave no gifts (#=-1)');
      });
    });

### Plural and Gender together

This example shows how you can specify gender rules for specific plural matches - in this case, =1 is special cased for gender.

    <div ng-controller="AppController">
    Select recipients:<br>
    <select multiple size=5 ng-model="recipients" ng-options="person as person.name for person in people">
    </select><br>
     <p>{{recipients.length, plural,
       =0 {{{sender.name}} has not given any gifts to anyone.}
       =1 {  {{recipients[0].gender, select,
              female { {{sender.name}} gave {{recipients[0].name}} her gift.}
              male { {{sender.name}} gave {{recipients[0].name}} his gift.}
              other { {{sender.name}} gave {{recipients[0].name}} their gift.}
             }}
           }
       other {{{sender.name}} gave {{recipients.length}} people gifts.}
       }}</p>

    function Person(name, gender) {
      this.name = name;
      this.gender = gender;
    }

    var alice   = new Person('Alice', 'female'),
        bob     = new Person('Bob', 'male'),
        harry   = new Person('Harry Potter', 'male'),
        ashley   = new Person('Ashley', '');

    angular.module('msgFmtExample', ['ngMessageFormat'])
      .controller('AppController', ['$scope', function($scope) {
          $scope.people = [alice, bob, ashley];
          $scope.recipients = [alice];
          $scope.sender = harry;
        }]);