897034 - Make l20n.js easy to download, test, install on github and the website

Status: NEW

(L20n :: Evangelism, defect, P2)

Description

[Pascal Chevrel:pascalc]

It's not easy to find where l20n.js is and get an example of how to use it for beginners.

There should be on both the website and the Github repo links to the library (normal and minified) and a very simple example file that people can download and test locally.

Comment 1

[Staś Małolepszy :stas]

I split the README into a few files inside the docs/ directory.  I have a WIP version at:

    https://github.com/stasm/l20n.js/tree/897034-discovery

Pascal, Flod:  can you guys take it from here and make changes as you see fit?

I also renamed the l20n.min.js directory to https://github.com/l20n/builds

Lastly, I took the multilocale-prod.html file from examples/ and copied it over to its own repo:

https://github.com/l20n/demo
http://l20n.github.io/demo/

Comment 2

[Francesco Lodolo [:flod]]

Main README file, I think there's one point that we should address (also for docs/api).

API Section

"When you freeze the context, the resource files will be retrieved, parsed and compiled."

But we don't explain what a context is, and why someone should need to freeze it or why localization could change.

Also about HTML Bindings, we should probably at least hint at the data-l10n-overlay attribute.

Some changes here
https://github.com/flodolo/l20n.js/commit/cbc3206ddf9dea30cc8deb33e41180c44588b45e

Comment 3

[Staś Małolepszy :stas]

I landed our WIP so far in https://github.com/l20n/l20n.js/commit/ad283b7cc46c01ac86ac520f3def96753ba3164c.  I think this is already much better and I want to avoid merge conflicts going forward.

Let's keep the bug open and make the docs even better.

Comment 4

[André Coelho]

My experience with l20n is that over time you guys have made it easier to actually get it working. Initially the library I got wouldn't work, then Stas directed me to another repo different from the one where I had gotten my version of the library and that solved it. Then we ran into some other issues that aren't related in any way to you guys but which Stas also helped solve. I think at this point what is mainly missing is a quicker/more direct route between the website where you can test drive l20n, and the places where you can get the library and set it up for your projects. In essence, I feel that that transition is the hardest part.