Screwdriver: Internationalize the Docs

[jer]

We would like to be able to support languages other than English, but it seems like mkdocs doesn't yet support this: https://github.com/mkdocs/mkdocs/issues/617

We need to figure out how to support this. Readthedocs could work, for instance: http://read-the-docs.readthedocs.io/en/latest/localization.html#localization-of-documentation

[stjohnjohnson]

Hmm, this is a great idea. It looks like there are two options:

• Use localization (string splitting)
• Use readthedocs sub-projects (separate copies of the documentation)

@catto what would be best for your team?

@petey what do you think about readthedocs.org?

Also, I grabbed http://screwdriver-cd.readthedocs.io/ and http://screwdriver-cd.rtfd.io/ in case we want it. I assume we'll also do https://guide.screwdriver.cd (or docs.).

[petey]

readthedocs is fine so long as we don't want to do anything fancy, like theming. I'm not sure if they support stuff that is dynamic, like the yaml page we have now, either.

[catto]

Actually, we haven't used any tools for localizing the documents. But updating the translated version will be heavy work if the repository or string is completely separated.
How about Sphinx+gh-pages? It supports theming and i18n by plugins. Nginx uses it for instance: https://www.nginx.com/resources/wiki/contributing/translating_docs/

Readthedocs is fine too. There is the document of trafficserver in Japanese and it seems to works well.
https://trafficserver.readthedocs.io/ja/latest/

[okuryu]

For many years, I have been worked on i18n docs for a lot of projects by different processes. I think they have both pros and cons for either of these ways.

I'm currently interesting in an another approach by Locki ( https://locki.io/ ). Node.js community is considering this right now (see: https://github.com/nodejs/node/issues/8798 ). I'm not sure it's best way for i18n docs, but I think it's be worth a try experimentally. Anyway, I'm ready to help on all i18n issues by any processes.

[chikathreesix]

Hi @okuryu, I am Ryo, a creator of Locki. Thanks for getting interested in our service!
We'd love to help Screwdriver's localization so feel free to ask me any questions, requests or concerns!
Also, check out this video to get more insight on how Locki works. https://youtu.be/c21-ac_26sk

[okuryu]

@chikathreesix good eye :)

[stjohnjohnson]

@okuryu @catto @chikathreesix We added Locki to the documentation at http://docs.screwdriver.cd/ and configured it for English and Japanese.

Can you take a look and try it out?

[chikathreesix]

@stjohnjohnson Awesome!

[catto]

@stjohnjohnson I did it and it looks good for now.
http://docs.screwdriver.cd/cluster-management/
Can you see my activities in Locki project?

@chikathreesix Locki is awesome 👍 so easy to use!

[stjohnjohnson]

@catto I can! That's awesome!

@chikathreesix Is there a way for people to offer a new language without me going to the project page and adding it?

[chikathreesix]

@stjohnjohnson You can add admin members from the team setting here to allow them to add a new language.
https://locki.io/projects/113/user_roles
But we are also implementing a way to make a request for a new language from the frontend.

[catto]

@chikathreesix Is there any way to include html tags into the translated messages?
I confirmed that some of the messages include html tags like below and it isn't reflected in the translated message.
http://docs.screwdriver.cd/user-guide/api/

[chikathreesix]

@catto Thanks for pointing that out! ul and li were removed when the content is sanitized so I have added those tags to the safe tags list. I fixed the section and confirmed it's now working fine.

[catto]

@chikathreesix I also confirmed it's working fine. Thank you for your support!

[chikathreesix]

@catto Thanks for confirming it. Ping me anytime via email at ryo at locki.io if you have any questions.

[okuryu]

Sorry for delay. Looks good to me, and it's probably good starting translations docs for us. 🤘