Add Locki to API documentation

[mikeal]

We do no currently have localizations for API documentation.

The system we use for the regular website is pretty heavy, doesn't port very well, and isn't very tolerant of regular changes.

Locki is a new service for creating a localization community and managing the translations.

Here is their URL: https://locki.io

/cc @chikathreesix who runs the service and can answer any questions or concerns people have.

[yosuke-furukawa]

That is pretty good. we are discussing about how to localize our API documentations. nodejs/docs#11 (comment)

CC: @nodejs/nodejs-ja

[chikathreesix]

Thank you @mikeal for posting this issue and thanks @yosuke-furukawa for your support!

Locki is a service that allows your website's visitor to translate your content right on your website by inserting a few lines of JS. Now you can also form your translation team like github to enable only your team to edit the translations so I believe this is really beneficial for OSS community like Node.js to translate its documentations.

Please try Locki by registering the API doc website to it and inserting the JS into your HTML.

If you have any questions, feel free to ask me anything. We have just launched so it might not have enough features but we are willing to build the features that the community want so give us any feedbacks!

[watilde]

This looks like what we wanted! In our use case of translation for the API docs, I guess we need to create a project on the locki for every single page of the docs since the segment has only the words which are used in the page we set, right? @chikathreesix

e.g.
https://locki.io/projects/22/segments

[chikathreesix]

Thanks for trying this out @watilde!
You don't need to register every single web pages. Once you register the root URL and insert JS to pages that belong to the root page and also you want to translate, Locki automatically add pages and also check updates when the pages get accessed.
So I guess in this case, you guys can register https://nodejs.org/api/ since nodejs.org has translated versions already.

[jasnell]

Key question is where the translations live. Are they hosted i Locki's content store? If so, what are the service guarantees so that those things don't disappear suddenly (not expecting that, of course, but just to be safe...)

[chikathreesix]

Hi @jasnell, currently we are hosting the data on the Postgres db on Heroku and fetching them from the API but will be switching to S3 in few weeks to directly host JSON files for the translations so that the translations will never disappear unless S3 is gone. In this case, you guys can also download the JSON files directly from S3 anytime as you like.

[jasnell]

@chikathreesix ... first off, great to meet you in person last night! Thank you for the clarification. What I'm mostly wanting to make sure is that the translations are backed up so this is great. I appreciate it. The other question I have is whether or not the translations could be version controlled in any way. Specifically, when a section of the documentation is modified, how are the changes those those individual sections handled? Would it continue to show the old translation or would there be some indication that something has changed and that an updated translation is required?

[mikeal]

As long as there is an export API we can pull down that export every day "just in case."

[chikathreesix]

Oh James, I am sorry I didn't recognize you from your comment. I am also really glad to meet you in person last night!

When we fetch a HTML, we parse them into something called "segments" which is basically equivalent to TextNode and translations belong to each segments. Whenever Locki finds a pages is updated, it creates a new segment for a updated TextNode which doesn't have any translations yet so translations will never be outdated, however, you need to translate every time it gets modified.
We are planning to implement some kind of notification to the team when it's updated and also show what was the previous TextNode at the same element as a reference.

In terms of a version control, we also save all the translation activities (like commits) to see who did what and also eventually to implement a feature to rollback to a specific point.
https://locki.io/projects/2/activities

[chikathreesix]

Hi all, I have integrated Locki here as an experiment. Try it there and give me feedbacks. Also let me know if you want to add more languages.
https://locki-nodejs-test.herokuapp.com/api/index.html

In order to edit, you need to create an account either from the module on the website or our platform https://locki.io

Although Locki automatically adds a page when getting accessed, it might take a few seconds to parse it so you might want to refresh the page if it doesn't show the boxes to edit.

[ChALkeR]

Will this affect only the API documentation (i.e. the /api/ dir)?

[chikathreesix]

@ChALkeR yup, you can do that so and I think that should the way in this case.

[ChALkeR]

@chikathreesix, is https://locki-nodejs-test.herokuapp.com/api/index.html the same as what it is actually going to look now? Some feedback then:

1. «Sign in with GitHub» is broken, and that's probably the option that would be most popular otherwise.

2. «Sign in with Facebook» is also broken, this leaves only one option available — manually registering on Locki website through email.

3. Switching between pages on the left resets the language to English.

4. The slideout animation is strange and inconvenient — I open the page, language selector gets loaded and shown after about 3 seconds. I see «English». I expect that I am able to change the language if I press that, I move mouse over «English», press it, but by that time it slides out on hover, running away from the mouse, so I miss the button I want to click and accidentally click on the link to the Locki website instead, which isn't what I wanted to do or what I expected to happen.

   That happened several times to me while I tried to get this working.

5. Some edit boxes don't look right on our documentation, see attached image — the box somewhy is zero-height and became a line. And users are supposed to click that box to be able to edit the text, as I understand things.

   

Those are all rather minor issues, but they will constantly get in the way of users who want to interact with that new feature. Note: I did not take a look at the actual translation tool yet, mostly because GitHub/Facebook auth does not work atm.

[ChALkeR]

One more issue just noticed: editor on https://locki.io/ (which doesn't actually allow to edit anything, but that's probably because I can't log in) sometimes just redirects to https://locki.io/undefined, which probably means that logic is broken somewhere. To reproduce:

1. Open https://locki.io/signin.
2. Switch Language, press «edit». All text snippets on the page gain borders, which probably signifies that they are editable.
3. Click on Email, Password, or or — it doesn't allow to edit, nothing happens.
4. Double-click on Email, Password, or or — you will get redirected to https://locki.io/undefined.