`ngMessageFormat`

Contents

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

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];
    }]);

Load online demo

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)');
  });
});

Load online demo

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;
    }]);

Load online demo