Repository navigation
Add Locki to API documentation #8798
Description
Activity
That is pretty good. we are discussing about how to localize our API documentations. nodejs/docs#11 (comment)
CC: @nodejs/nodejs-ja
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!
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
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/ sincenodejs.orghas translated versions already.Reacted by Daijiro WachiReacted by Daijiro WachiReacted by Daijiro WachiKey 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...)
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.
@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?
As long as there is an export API we can pull down that export every day "just in case."
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/activitiesHi 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.htmlIn 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.
Will this affect only the API documentation (i.e. the
/api/dir)?@ChALkeR yup, you can do that so and I think that should the way in this case.
@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:
-
«Sign in with GitHub» is broken, and that's probably the option that would be most popular otherwise.
-
«Sign in with Facebook» is also broken, this leaves only one option available — manually registering on Locki website through email.
-
Switching between pages on the left resets the language to English.
-
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.
-
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.
-
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:
- Open https://locki.io/signin.
- Switch Language, press «edit». All text snippets on the page gain borders, which probably signifies that they are editable.
- Click on
Email,Password, oror— it doesn't allow to edit, nothing happens. - Double-click on
Email,Password, oror— you will get redirected to https://locki.io/undefined.
11 remaining items
@chikathreesix I can confirm that GitHub auth works now, but Facebook auth still fails with the same error.
@ChALkeR I think the proposal is to allow the localization be editable by the community and the access controls maintained by whatever system Locki has. For most localizations that is probably preferred, most of the localization communities we have in our GitHub org are a subset of a much larger community in that locale.
@ChALkeR I got the issue with your facebook account and now it should be fixed.
@ChALkeR and @mikeal
Although you can also limit the editing to nodejs org members only first not to be messed up by random people, the idea of Locki is to open up the funnel more specifically for the localization since the bar for getting into the localization community with Locki becomes easier. So I think the localization specific community eventually might be consist of a bit different members from the core nodejs community.While playing around with the tool, I found this:
There is some HTML that wasn't isolated.
@ChALkeR oh, since you are using a same email address as github, you can't create a new account with facebook. Let us think what would be the best way to solve this.
@targos This is an expected behavior since you might need to change positions of anchor, span, strong tags and so on which appears in a paragraph. So it groups inline elements into a segment.
I agree that it should be nicer in terms of displaying them so we are thinking about display the tags in a simplified format or something else not to show the entire tags.oh, since you are using a same email address as github, you can't create a new account with facebook. Let us think what would be the best way to solve this.
I don't think that this is very important (logging in from two accounts), the good thing is that everyone could log in through their preferred way.
This bug is kind of moving into a bug report for locki. My impression reading this is that it doesn't seem mature enough to provide a consistent experience for the animation/popup (which for me is a tradeoff). Going to agree with @ChALkeR in that in its current state its a
-1.Also, if we're doing this I'd like to see a similar solution to what we discussed in the analytics issue -- add a flag/env var so its turned off by default should documentation be built/read locally.
@jbergstroem Thanks for your feedback. What do you mean by a consistent experience for the animation/popup?
@ChALkeR Issue 3 and 6 was already fixed. For issue 5. weird box definition, I found that that the height of the element is defined 0px in its CSS so we can't fix this from our-end.
I think we need to collect more opinions about this.
And I would like to hear other localization WG voice.
I will open same issue on nodejs.org repos.Oops, I have not read nodejs.org issue guideline. according to that, API docs problem should be discussed on nodejs/node repo.
I would like to progress this issue. Someone has downvote, but someone has upvote, we need to gather more opinions to judge how to handle i18n API docs.
CC: @nodejs/localizationFor issue 5. weird box definition, I found that that the height of the element is defined 0px in its CSS so we can't fix this from our-end.
Ah, I see, thanks. Then, it should be fixed on our end.
Current rules (doc/api_assets/style.css#L305-L310):#toc h2 { margin-top: 0; font-size: 1em; line-height: 0; margin: 1.5em 0; }
Not sure why that combination of margins and zero line-height was introduced… It's since #297.
This issue has been inactive for sufficiently long that it seems like perhaps it should be closed. Feel free to re-open (or leave a comment requesting that it be re-opened) if you disagree. I'm just tidying up and not acting on a super-strong opinion or anything like that.
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.