Allow for multi-language documentation

[Scott Sauyet]

ramda/ramda#1951 suggested a translation of the documentation into Chinese. I think this would be a great idea, and of course, we shouldn't be limited to just Chinese, but to whatever languages we had the volunteers to support.

There are technical issues of course, but also some non-technical ones:

• How many volunteers do we need for a particular language? Ramda isn't moving as quickly as it once did, but it's certainly not a static target, and releases tend to happen fairly quickly. Even if we got ourselves more organized about that, we would need to know that all new and changed functions were properly translated.
• We should probably also translate the release notes, if possible. Do we also try to do the home page and the Wiki pages?
• Do we seek out volunteers for likely languages, trying to cover some large segment of the developer community? Or do we simply wait for volunteers to appear to begin including a new language?
• Do we allow a lag between when a version is published with up-to-date English documentation and when the translations are published? Or do we ensure that all translations are completed before publishing a version?

Or do we skip all this and not worry about such details given that we have at the moment a single volunteer for a single language? Should we just work out the technical kinks and assume the rest will be resolved when the need arises?

A very brief start at a technical solution

If we separate the JSDoc tags from the code, then we could easily support multiple versions. I'm imagining something like:

src/filter.js:

var _curry2 = require('./internal/_curry2');
var _dispatchable = require('./internal/_dispatchable');
var _filter = require('./internal/_filter');
var _isObject = require('./internal/_isObject');
var _reduce = require('./internal/_reduce');
var _xfilter = require('./internal/_xfilter');
var keys = require('./keys');


/** @sig Filterable f => (a -> Boolean) -> f a -> f a */

module.exports = _curry2(_dispatchable('filter', _xfilter, function(pred, filterable) {
  return (
    _isObject(filterable) ?
      _reduce(function(acc, key) {
        if (pred(filterable[key])) {
          acc[key] = filterable[key];
        }
        return acc;
      }, {}, keys(filterable)) :
    // else
      _filter(pred, filterable)
  );
}));

api/filter.api:

/**
 * Takes a predicate and a "filterable", and returns a new filterable of the
 * same type containing the members of the given filterable which satisfy the
 * given predicate.
 *
 * Dispatches to the `filter` method of the second argument, if present.
 *
 * Acts as a transducer if a transformer is given in list position.
 *
 * @category List
 * @param {Function} pred
 * @param {Array} filterable
 * @return {Array}
 * @see R.reject, R.transduce, R.addIndex
 * @example
 *
 *      var isEven = n => n % 2 === 0;
 *      R.filter(isEven, [1, 2, 3, 4]); //=> [2, 4]
 *      R.filter(isEven, {a: 1, b: 2, c: 3, d: 4}); //=> {b: 2, d: 4}
 */

api/langs/zh/filter.api (and please forgive the surely awful machine translation):

/**
 * 需要一个谓语和一个“过滤”，并返回一个包含给定的过滤满足给定谓词的成员相同类型的新筛选
 *
 * 分派给第二个参数，如果存在`filter`方法。
 *
 * 如果变压器在列表中的位置给出充当传感器。
 *
 * @category 名单
 * @param {功能} pred
 * @param {排列} filterable
 * @return {排列}
 * @see R.reject, R.transduce, R.addIndex
 * @example
 *
 *      var Shènzhì = n => n % 2 === 0;
 *      R.filter(Shènzhì, [1, 2, 3, 4]); //=> [2, 4]
 *      R.filter(Shènzhì, {a: 1, b: 2, c: 3, d: 4}); //=> {b: 2, d: 4}
 */

(Or perhaps we don't put the English version at the root, but only in api/langs/en. That's just a detail.)

Then at build time, for each language, we marry these docs with the functions and run JSDoc, generating a langauge-specific API documentation folder. Obviously there would be work to do on the documentation template to allow the user to switch languages as well.

Does this sound as though it would work? Does it sound like too much effort? What do people think?

[Scott Sauyet]

Just beat to this. See #147.