app-localize-behavior.html

<!--
@license
Copyright (c) 2016 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../iron-ajax/iron-ajax.html">
<script src="../intl-messageformat/dist/intl-messageformat.min.js"></script>

<script>

/**
* `Polymer.AppLocalizeBehavior` wraps the [format.js](http://formatjs.io/) library to
* help you internationalize your application. Note that if you're on a browser that
* does not natively support the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
* object, you must load the polyfill yourself. An example polyfill can
* be found [here](https://github.com/andyearnshaw/Intl.js/).
*
* `Polymer.AppLocalizeBehavior` supports the same [message-syntax](http://formatjs.io/guides/message-syntax/)
* of format.js, in its entirety; use the library docs as reference for the
* available message formats and options.
*
* Sample application loading resources from an external file:
*
*     <dom-module id="x-app">
*        <template>
*         <div>{{localize('hello', 'name', 'Batman')}}</div>
*        </template>
*        <script>
*           Polymer({
*             is: "x-app",
*
*             behaviors: [
*               Polymer.AppLocalizeBehavior
*             ],
*
*             properties: {
*               language: {
*                 value: 'en'
*               },
*             }
*
*             attached: function() {
*               this.loadResources(this.resolveUrl('locales.json'));
*             },
*           });
*        &lt;/script>
*     </dom-module>
*
* Alternatively, you can also inline your resources inside the app itself:
*
*     <dom-module id="x-app">
*        <template>
*         <div>{{localize('hello', 'name', 'Batman')}}</div>
*        </template>
*        <script>
*           Polymer({
*             is: "x-app",
*
*             behaviors: [
*               Polymer.AppLocalizeBehavior
*             ],
*
*             properties: {
*               language: {
*                 value: 'en'
*               },
*               resources: {
*                 value: function() {
*                   return {
*                     'en': { 'hello': 'My name is {name}.' },
*                     'fr': { 'hello': 'Je m\'apelle {name}.' }
*                   }
*               }
*             }
*           });
*        &lt;/script>
*     </dom-module>
*
* @demo demo/index.html
* @polymerBehavior Polymer.AppLocalizeBehavior
*/
Polymer.AppLocalizeBehavior = {
  /**
   * Internal singleton cache. This is the private implementation of the
   * behaviour; don't interact with it directly.
   */
  __localizationCache: {
    requests: {},  /* One iron-request per unique resources path. */
    messages: {},  /* Unique localized strings. Invalidated when the language, formats or resources change. */
    ajax: null     /* Global iron-ajax object used to request resource files. */
  },

  /**
   * If the element is using `pathToResources` to load an external resources
   * file, fired when the file has been loaded.
   *
   * @event app-localize-resources-loaded
   */

  /**
   * If the element is using `pathToResources` to load an external resources
   * file, fired when the file cannot be loaded due to an error.
   *
   * @event app-localize-resources-error
   */

  properties: {
    /**
     * Fallback language to use if a string cannot be found in the desired language
     */
    defaultLanguage: {
      type: String
    },

    /**
     * The language used for translation.
     */
    language: {
      type: String
    },

    /**
     * The dictionary of localized messages, for each of the languages that
     * are going to be used. See http://formatjs.io/guides/message-syntax/ for
     * more information on the message syntax.
     *
     * For example, a valid dictionary would be:
     * this.resources = {
     *  'en': { 'greeting': 'Hello!' }, 'fr' : { 'greeting': 'Bonjour!' }
     * }
     */
    resources: {
      type: Object
    },

    /**
     * The path to the dictionary of localized messages. The format is the
     * same as the `resources` array, only saved as an external json file.
     * Note that using a path will populate the `resources` property, and override
     * the previous data.
     */
    pathToResources: {
      type: String
    },

    /**
     * Optional dictionary of user defined formats, as explained here:
     * http://formatjs.io/guides/message-syntax/#custom-formats
     *
     * For example, a valid dictionary of formats would be:
     * this.formats = {
     *    number: { USD: { style: 'currency', currency: 'USD' } }
     * }
     */
    formats: {
      type: Object,
      value: function() { return {} }
    },

    /**
     * If true, will use the langauge in the defaultLanguage property
     * when the translation does not exist for that key.
     */
    useDefaultLanguageIfMissing: {
      type: Boolean,
      value: false
    },

    /**
     * If true, will use the provided key when
     * the translation does not exist for that key.
     */
    useKeyIfMissing: {
      type: Boolean,
      value: false
    },

    /**
     * Translates a string to the current `language`. Any parameters to the
     * string should be passed in order, as follows:
     * `localize(stringKey, param1Name, param1Value, param2Name, param2Value)`
     */
    localize: {
      type: Function,
      computed: '__computeLocalize(language, resources, formats)'
    }
  },

  loadResources: function(path) {
    var proto = this.constructor.prototype;

    // In the event proto not have __localizationCache object, create it.
    if(proto['__localizationCache'] === undefined) {
      proto['__localizationCache'] = {requests: {}, messages: {}, ajax: null};
    }

    // If the global ajax object has not been initialized, initialize and cache it.
    var ajax = proto.__localizationCache.ajax;
    if (!ajax) {
      ajax = proto.__localizationCache.ajax = document.createElement('iron-ajax');
    }

    var request = proto.__localizationCache.requests[path];
    if (!request) {
      ajax.url = path;
      var request = ajax.generateRequest();

      request.completes.then(
          this.__onRequestResponse.bind(this),
          this.__onRequestError.bind(this));

      // Cache the instance so that it can be reused if the same path is loaded.
      proto.__localizationCache.requests[path] = request;
    } else {
      request.completes.then(
          this.__onRequestResponse.bind(this),
          this.__onRequestError.bind(this));
    }
  },

  /**
   * Returns a computed `localize` method, based on the current `language`.
   */
  __computeLocalize: function(language, resources, formats) {
    var proto = this.constructor.prototype;

    // Everytime any of the parameters change, invalidate the strings cache.
    proto.__localizationCache.messages = {};

    return function() {
      var key = arguments[0];
      if (!key || !resources || !language || !resources[language])
        return;

      // Cache the key/value pairs for the same language, so that we don't
      // do extra work if we're just reusing strings across an application.
      var translatedValue = resources[language][key];

      // fallback to using the translation from the default language
      // if enabled
      if (
        !translatedValue &&
        this.useDefaultLanguageIfMissing &&
        this.defaultLanguage &&
        resources[this.defaultLanguage]
      ) {
        translatedValue = resources[this.defaultLanguage][key];
      }

      if (!translatedValue) {
        return this.useKeyIfMissing ? key : '';
      }

      var messageKey = key + translatedValue;
      var translatedMessage = proto.__localizationCache.messages[messageKey];

      if (!translatedMessage) {
        translatedMessage = new IntlMessageFormat(translatedValue, language, formats);
        proto.__localizationCache.messages[messageKey] = translatedMessage;
      }

      var args = {};
      for (var i = 1; i < arguments.length; i += 2) {
        args[arguments[i]] = arguments[i+1];
      }

      return translatedMessage.format(args);
    };
  },

  __onRequestResponse: function(event) {
    this.resources = event.response;
    this.fire('app-localize-resources-loaded');
  },

  __onRequestError: function(event) {
    this.fire('app-localize-resources-error');
  }
}

</script>