@ngdoc overview
@name Custom Interpolators
@description

# Custom Interpolators

If you're smart enough to implement a smaller MessageFormat library, or if you
just need another type of interpolation, you can simply build your own interpolation
service and plug it into angular-translate. All you have to do is to follow a
specific interface angular-translate expects from an interpolation service. Let's
see how things work!

## Building a custom interpolation service

When building a custom interpolation service, things should be pretty familiar
if you've read [Custom Storages](#/guide/11_custom-storages) and
[Custom Loaders](#/guide/13_custom-loaders). You start with building a factory
that returns an object that implements a certain interface. The following methods
have to be provided by a custom interpolation service:

- `setLocale(langKey)` - sets the currently used language
- `getInterpolationIdentifier()` - returns an identifier for interpolation
- `interpolate(string, interpolateParams, context, sanitizeStrategy, translationId)` - interpolates strings against interpolate params

Let's see how it looks like when implementing a custom interpolation service. First,
we implement the interface:

<pre>
app.factory('customInterpolation', function () {

  return {

    setLocale: function (locale) {

    },

    getInterpolationIdentifier: function () {

    },

    interpolate: function (string, interpolateParams, context, sanitizeStrategy, translationId) {

    }
  };
});
</pre>

Okay, this is the basic structure of an interpolation service. Now let's add some
logic, so angular-translate can make use of it once our custom interpolation service
comes in:

<pre>
app.factory('customInterpolation', function ($interpolate, $translateSanitization) {

  var $locale;

  return {

    setLocale: function (locale) {
      $locale = locale;
    },

    getInterpolationIdentifier: function () {
      return 'custom';
    },

    interpolate: function (string, interpolateParams, context, sanitizeStrategy, translationId) {
      string = $translateSanitization.sanitize(string, 'text', sanitizeStrategy);
      if (interpolateParams) {
        interpolateParams = $translateSanitization.sanitize(interpolateParams, 'params', sanitizeStrategy);
      }
      return $locale + '_' + $interpolate(string)(interpolateParams) + '_' + $locale;
    }
  };
});
</pre>

Alright. So what did we do here. `setLocale()` simply store the value of the current
used language. `getInterpolationIdentifier()` returns a string `custom`. So what is
it actually for? Remember how to
[temporarily override the interpolation type](#/guide/14_pluralization#overridinginterpolationtemporarily)?
Exactly. This is the identifier that is mapped to your service, so angular-translate
knows which interpolation services to use, when you explicitly override interpolation
service at runtime. `interpolate()` simply uses Angular's `$interpolate` service.
In addition it prepends and appends the current locale to the given string.

It is important to remember about [proper sanitazion](#/guide/19_security) before calling Angular's `$interpolate` function. 
For this purpose you can use `$translateSanitization` service, which utilizes the current sanitation 
strategy, that is set with `$translateProvider.useSanitizeValueStrategy()` function during config.

## Using your custom interpolation service

Just like there's a method for Storages (`useStorage()`) and Loaders (`useLoader()`),
there's also a method for custom interpolations. `$translateProvider.useInterpolation()`
is your friend when it comes to integrate your custom interpolation service into
your app.

<pre>
$translateProvider.useInterpolation('customInterpolation');
</pre>

You app now uses your custom interpolation as default. However, as you've learned
in previous chapters, you can add your custom interpolation as optional interpolation,
not to loose Angular's cool features:

<pre>
$translateProvider.addInterpolation('customInterpolation');
</pre>

Here' what it looks like:

<doc:example module="myApp">
  <doc:source>
    <script>
      var app = angular.module('myApp', ['pascalprecht.translate']);

      app.config(['$translateProvider', function ($translateProvider) {
        $translateProvider.preferredLanguage('en');
        $translateProvider.useInterpolation('customInterpolation');

        $translateProvider.translations('en', {
          HEADLINE: 'I\'m a headline',
          TEXT: 'I\'m using default interpolation {{ val + val }}',
          PLURAL: '{GENDER, select, male{He} female{She} other{They}} liked this.',
          BUTTON_LANG_EN: 'English',
          BUTTON_LANG_DE: 'German'
        });

        $translateProvider.translations('de', {
          HEADLINE: 'Ich bin eine Überschrift',
          TEXT: 'Ich benutze default interpolation {{ val + val }}',
          PLURAL: '{GENDER, select, male{Er fand} female{Sie fand} other{Sie fanden}} es gut.',
          BUTTON_LANG_EN: 'Englisch',
          BUTTON_LANG_DE: 'Deutsch'
        });
      }]);

      app.controller('Ctrl', ['$translate', '$scope', function ($translate, $scope) {

        $scope.changeLanguage = function (langKey) {
          $translate.use(langKey);
        };
      }]);

      app.factory('customInterpolation', function ($interpolate, translateSanitization) {

        var $locale;

        return {

          setLocale: function (locale) {
            $locale = locale;
          },

          getInterpolationIdentifier: function () {
            return 'custom';
          },

          interpolate: function (string, interpolateParams, sanitizeStrategy) {
            string = $translateSanitization.sanitize(string, 'text', sanitizeStrategy);
            if (interpolateParams) {
              interpolateParams = $translateSanitization.sanitize(interpolateParams, 'params', sanitizeStrategy);
            }
            return $locale + '_' + $interpolate(string)(interpolateParams) + '_' + $locale;
          }
        };
      });

    </script>
    <div ng-controller="Ctrl">
      <p translate="HEADLINE"></p>
      <p translate="TEXT" translate-values="{ val: 5 }"></p>

      <button ng-click="changeLanguage('de')" translate="BUTTON_LANG_DE"></button>
      <button ng-click="changeLanguage('en')" translate="BUTTON_LANG_EN"></button>
    </div>
  </doc:source>
</doc:example>


<br>
<hr>
<center>Made with unicorn &hearts; love by [PascalPrecht](http://github.com/PascalPrecht)</center>
