How to translate Chapel Doc

[marcoscleison]

Dear Chapel Devs, thanks for all efforts on coding this beautiful language. I would like to know what is the procedure to translate the Chapel documentation and make a pull request.
Should I create a folder with language ISO code (like pt-Br, zh-Zh etc.) and put translated rst files there?

I know that this is not a high priority issue for the project, but it would be good to have some guideline about translating Chapel language documentation.

Thank you very much.

[bradcray]

For me, the main challenge in considering any non-English language translation of Chapel documentation is how to ensure it is maintained over time, which leads quickly to a question as to how much of the documentation should be translated. Enough is in flux simply in the English version of the documentation that maintaining a significant fraction of the documentation in multiple different languages seems daunting. Do you have thoughts as to how to make this tractable or about what subset of the documentation would be most useful to have translated to different languages?

I'll also note that, anecdotally, a higher-up in our organization who happens to be a non-native English speaker expressed surprise that translating Chapel's docs would be worthwhile given the level of maintenance effort it would impose -- his impression was that technical people from his country were accustomed to needing to rely on their English when dealing with technical documentation. I don't have sufficient international experience myself to know any better, though.

[lydia-duncan]

One suggestion I had on that front is to have a warning on the documentation that has been generated, so that readers are told ahead of time when the last update for any particular page occurred. Such a warning could include a request for assistance on performing the translation (something along the lines of "The most active developers on the team don't speak language X. If you have the time and the skills, we would greatly appreciate any page or partial page you can translate at this time").

[lydia-duncan]

Note also that this is a problem that a lot of Open Source projects struggle with. I find it really exciting that we have the following to start on this sort of effort :)

[lydia-duncan]

Aside from that, @marcoscleison: what would you like your experience with these pages to entail? Would you like them to be provided on the web in the same location as the online documentation today?

With all the pages for a particular language grouped together on the sidebar?

With each page that has a translation listing its translations on that page?

Something else entirely?

(Note that I'm not certain about how possible it is to do some of these actions within our documentation set up today and that various approaches would have varying levels of difficulty. We can aim for an ideal future as well as a "what can we get running now" approach)

[ben-albrecht]

Ditto mostly what @bradcray said.

If we were going to pursue this, I'd look to other languages to see what they are doing, and if it's working well for them or not.

[marcoscleison]

I think that your opinions are wise words.

After reading your opinions and thinking a little about it, I concluded that this issue is like double edged-sword. On one side, we know how hard is to maintain the documentation translated into other languages. On the other side, we have a huge mass of programmers that does speak English that could use Chapel to solve general problems, not only related to HPC. I know the moto of Chapel is HPC environment, but I think that the language is useful to solve problems in other fields such as web backend, utilities and so on.

The main motivation to translate is making people know the existence os such beautiful language.

I understand @bradcray when he cites the higher-up saying: "his impression was that technical people from his country were accustomed to needing to rely on their English when dealing with technical documentation.". It is very logical if you consider that the programmer is a Phd or Master student that wants to solve some HPC using Chapel. In this situation, English is needed to read papers.

However, there is a huge world of people that works with programming that does not master English, only the keywords and the logic of programming. These are people that want some sort of simple parallel language to solve relatively simple problems. Ex. A web backend developer was wanting use chapel to process batch text content in its multicore server. For him, Hadoop does not apply and he wants a language that can have coarse-grained control of parallelism, the best option was Chapel, but the lack of documentation in his language make a real barrier. Sadly he switched to Google Go, because it has plenty docs in the language, other than English.

I would like to have full-time in order to work with all chapel translation to Portuguese, for example, however, this is not my situation, but I think that we should have a guideline to those who want to translate.

I have a suggestion.

Why don't we get some small subset of doc and call for a joint translation team? I think that Chapel primers would be a good start. We could make some warning about the responsibility of chapel teams on languages other than English and make a kind of wiki where people can translate Chapel premiers, for example.

I understand you. We should think in a creative and cheap solution, somewhat that not overload your work.

@lydia-duncan we could put a link to the unofficial translation of Chapel primers in the sidebar menu.

Finally, I am not saying that developers of my country are incapable of reading in English. I just want to say that would be good to have some documentation in the language to attract and facilitate people keep in touch with this amazing project.

I really appreciate your efforts and I am open to listening suggestions.

Thanks.