Document Translation

[SucculentAnimal]

Hi, I saw this project is getting popular in Japan, And since this project is very well-documented (It was very helpful, Thanks!), I was wondering can i help for translating documents?

I can only help for Chinese(mandarin) and Japanese part, but I think this might be very helpful for non-english speaker.

[wez]

I saw @yutkat's article and the subsequent buzz on twitter from the Japanese audience!
I like the idea of making the documentation more accessible, but I have concerns about maintenance and scaling it across a pool of volunteers.

• There's some activation cost involved in figuring out how to host and track the translations. Maybe there are features in mdbook that can help, but otherwise, it's probably just a matter of adding a sub directory per language. That's the easy bit.
• For languages which I don't read fluently (realistically, that's everything other than English), I have no good way (beyond Google Translate) to evaluate whether the content is either factually accurate or carries the same meaning as the English language text. It would be good to have at least another person that is fluent in English + the target language to review and give feedback on that content.
• The non-English translations will be perpetually in a state of lagging behind the English text. If the difference is too large, the translation can become a liability rather than be helpful.
• It would be good to have a strategy in mind that minimizes the effort required to understand the lag, or to minimize the effects of the lag. For instance, prioritizing translating general concepts feels like it might be good to help people that are new to the software figure out how to set it up. It's perhaps less important to cover 100% of the reference section.
• Having a way to convey how much of a lag there is between a translation and the English version of a page to the reader feels like it would be valuable. We'd need to automate this, but having the doc build notice that the English version was changed more recently than say the Japanese version and then emitting a note into the page in question to inform the reader and providing a link to the English version of the docs feels probably good.
• I'd like to avoid eg: doing a one-time translation and then leaving that text to bit-rot. Since I cannot realistically maintain those other languages, I'd be looking for someone to volunteer to make a commitment to maintain the translation and keep it up to date with the English text within some reasonable lag period (some reasonable number of weeks?) to prevent the text from losing its value to users.
• I don't want those volunteers to feel like they are forever tied to maintaining this stuff, so we should probably structure things to make it easier to crowdsource help. For instance, in the automation that surfaces whether a translation is stale, we could encourage user contributions to bring it up to date (eg: link to the edit on github feature for a given page) and make that more prominent (bold) when the page is very stale (more than some number of edits, or elapsed time between the last page change).

So, I'd welcome the contribution, but we need to be smart about how we manage it so that it remains valuable beyond the initial submission!

What do you think about this? Do you have examples of other opensource projects that do a good job with translating their docs?

[yutkat]

Wow, I am honored to have you read my article 😄

In my opinion, it would also be better if there was documentation in Japanese, but wezterm's documentation was not so difficult in English for me.

I know of two successful translations into Japanese (https://github.com/vim-jp/vimdoc-ja, https://www.archlinux.jp), both of which were worked on by the community, and I have heard that the work is not easy. The tough part is keeping up with the latest version and finding the right people to work on it.
If you decide to translate it into Japanese I can help.

[SucculentAnimal]

Thank You For Your Quick Response.
I just did a quick research, but I have a few things coming up right now so It's not a good time for me to list all issues and solutions.
I will respond later. Thanks.

EDIT: Issue created. Please visit #1705 for more information.