Review Gulp Guidelines

[kahnvex]

To encourage community investment in this plugin, I think we should review the Gulp Guidelines. The main thing I've noticed is the plugin is doing too much:

Your plugin should only do one thing, and do it well.

• Avoid config options that make your plugin do completely different tasks
• For example: A JS minification plugin should not have an option that adds a header as well

I think the JSON URL prefixer should be it's own plugin.

I think if we follow these guidelines within reason, this plugin, and others Yola open sources, can be successfully supported by the larger community. At the very least, considering these guidelines can help us stay off the gulp blacklist.

@stefanor @beck

[beck]

Yeah, the Gulp Guidelines are good, and they do apply.

I think the JSON URL prefixer should be it's own plugin.

No, not just the prefixer—all of the translation code. There should be a standalone static-i18n translation tool with a proper CLI. The gulp plugin should be a thin wrapper around static-i18n and then we will be conforming to the guidelines.

Translation with static-i18n would ideally pair with extraction using jsxgettext. jsxgettext will be undergoing architecture changes to extract all language parsers to their own repos.

I'm imagining something like:

• gulp-static-i18n - gulp plugin for static-i18n
• static-i18n - node tool for translating files statically using parser plugins
• jsxgettext - node tool for extracting translation messages from files using parser plugins
• i18n-parser-json - parser plugin for jsxgettext & static-i18n
• i18n-parser-js - parser plugin for jsxgettext & static-i18n
• i18n-parser-handlebars - parser plugin for jsxgettext & static-i18n
• i18n-parser-html - parser plugin for jsxgettext & static-i18n
• etc

[kahnvex]

👍 👍

[tSte]

I like this project, but I think it would be great if it was a real gulp plugin.

Currently, you will do your stuff (minify, compile, etc.) in separate task and pipe it to a distribution folder. Then you translate every script in this folder. If you need post-translate processing (I know it's rare, but it can happen), you do it in third task. Right? Stuff like this:

gulp.task('compile', () => {
    // Process scripts
});

gulp.task('translate', ['compile'], () => 
    gulp.src('dist').pipe(staticI18n()));

gulp.task('modify-translated', ['translate'], () => {
    // Process scripts
});

If you think about it, you can replace the translate task with something like this:

gulp.task('trasnlate', ['compile'], (cb) => staticI18n({ source: 'dist', done: cb }));

or even this:

staticI18n({ source: 'dist' });

You don't really need gulp for this, because it does not behave like a gulp plugin.

I think it would be great if it worked like this:

gulp.task('scripts', () => gulp
    .src('./your/sources/**.js')
    .pipe(yourPreTranslateProcessor())
    .pipe(staticI18n(yourOptions))
    .pipe(yourPostTranslateProcessor())
    .pipe(gulp.dest('dist'))
);

Why? Well, for number of reasons:
1.) It would be an actual gulp plugin.
2.) I can have one task for all pre-translate, translate and post-translate processing.
3.) I can decide what should be translated.

Imagine ES6 module-based app translated into 4 languages. In our case, only ~10% of ~230 modules ale localized. I don't want to have 920 (4x230) .js files in our WebServer cache. 299 (4x23 = 92 + 207) is much better. Currently, I can't decide which modules should or should not be translated. And if I want to modify import paths to localized modules (import foo from './foo' => import foo from './en/foo') after translation, I need other task.

[tSte]

If you guys plan to maintain this, I can help you...

[beck]

Hi @tSte! Thanks for your interest in this project.

Correct me if I'm wrong, I think a different way to phrase your request is:

Return a stream instead of writing to a configured destination.

This is a sensible API change. Such work is not necessarily related to this particular ticket and can happen before/after this ticket (almost certainly before since I don't had much time to devote to this project). I would gladly review and accept a pull request.

As for post-processing, it can still be done—one would configure the post-processing task to consume files from the dest folder. Maybe not ideal but easily doable. Either way, this tool will be a bit unconventional because for every 1 file in, there are N files out (one for each supported language).