docs(options): explain attributes option

[zewa666]

explain what the custom attributes option is used for, what the defaults are and why there is a need to register them in two places.

Fixes issue https://github.com/aurelia/i18n/issues/222

[zewa666]

@dkent600 any chance you can give this PR a look and see whether it clarifies your issue?

[dkent600]

@zewa666 The doc text is OK, but I wonder if it would be better if TCustomAttribute.configureAliases were called "under the hood" inside of I18N.setup?

This would be cleaner.

[zewa666]

yeah that would be nice, but as said timing is the issue why we can't do that. So once the plugins setup is happening, templates are already evaluated and thus custom elements / attributes added via globalResources or features won't understand the aliases.

Sadly I do not see another way to solve this currently, but its definitely something on the todo list.

[dkent600]

@zewa666

I guess I don't understand since TCustomAttribute.configureAliases can be called immediately before I18N.setup (by setup I am referring to the aurelia-i18n wrapper around I18Next.init), why there is this issue with timing where one can't just stuff it into the aurelia-i18n setup method and call it first thing, prior to I18Next.init. The timing is no different.

The code would look something like this:

I18N.prototype.setup = function setup(options) {
    var _this2 = this;

    var defaultOptions = {
      compatibilityAPI: 'v1',
      compatibilityJSON: 'v1',
      lng: 'en',
      attributes: ['t', 'i18n'],
      fallbackLng: 'en',
      debug: false
    };

   options = options || defaultOptions;
   TCustomAttribute.configureAliases(options.attributes);

    i18next.init(options, function (err, t) {
      if (i18next.options.attributes instanceof String) {
        i18next.options.attributes = [i18next.options.attributes];
      }

      _this2.i18nextDefered.resolve(_this2.i18next);
    });

    return this.i18nextDefered.promise;
  };

[zewa666]

Because this part is as mentioned executed after global registrations of other templates. So any use of a alias would result in not being handled by i18n. The reason is that Aurelias bootstrapping first processes all features, global registrations and then all plugins. As such as soon you're inside a plugin it's to late to apply the alias registration